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PREFACE 


MANUAL OBJECTIVES 


The VAX/VMS Real-Time User's Guide describes VAX/VMS features of 
interest to real-time application programmers. It describes in 
general terms functions common to a variety of real-time applications 
and explains the specific VAX/VMS feacures available to perform these 
functions. This manual also contains numerous examples, including 
coding segments and complete programs, to illustrate certain important 
or complex features. 





INTENDED AUDIENCE 


This manual is intended for programmers writing real-time 
applications. You are assumed to have substantial programming 
experience and some knowledge of basic VAX/VMS concepts (see 


"Associated Documents" in this preface). 


The programming examples are in VAX-11 MACRO and VAX-11 FORTRAN. Each 
example, however, is designed to be as meaningful as possible for 
programmers using any other VAX-11 language. 


STRUCTURE OF THIS DOCUMENT 


This manual covers a variety of topics, usually proceeding from less 
complex to more complex material. Wherever appropriate, this manual 
relates a topic to other topics discussed elsewhere in the manual. 


Chapter 1 introduces the manual. It summarizes the real-time features 
covered in the manual, describes other features of possible interest 
and refers to appropriate documentation, and explains some significant 
concepts. 


Chapter 2 discusses ways to control the program execution environment, 
including creating subprocesses and detached processes and affecting 
the allocation of physical memory. 


Chapter 3 covers mechanisms for communicating between cooperating 
processes, synchronizing their activities, and sharing data and code. 


Chapter 4 discusses real-time I/0, including mapping I/O space and 
connecting to a device interrupt vector. : 


Chapter 5 discusses the use of software facilities located in 


multiport (shared) memory -- specifically common event flag clusters, 
mailboxes, and global sections. 


vil 


Chapter 6 explains privileged shareable images, a vehicle that allows 
you, in effect, to write your own system services, 


Chapter 7 provides several complete programming examples with 
accompanying explanations. 


The appendixes present supplementary information. Appendix A_ shows 
how to use a common event flag or a queue as a mutual exclusion 
(mutex) semaphore to lock a_ resource, Appendix B discusses 
programming and design considerations for users of the Laboratory 
Peripheral Accelerator (LPAl1-K). Appendix C provides a programming 
example in VAX-11 BLISS-32. Appendix D is a checklist of optimization 
techniques for real-time users. 


ASSOCIATED DOCUMENTS 


The following manuals explain the VAX/VMS concepts that are 
prerequisite knowledge for readers of this manual: 


e The VAX/VMS Summary Description and Glossary explains the 


major components of the VAX/VMS system and defines significant 
terms. 





e The VAX- 11/780 Technical Summary (order number EA-15963-20) 


describes the major components and features of the VAX/VMS 
system. 





The following manuals provide more detailed treatment of major 
concepts and features described in this manual: 


e The VAX/VMS System Manager's Guide discusses the system 


generation (SYSGEN) utility, the user authorization file 
(UAF), system tuning, and the DISPLAY utility. 





e The VAX/VMS System Services Reference Manual provides tutorial 


chapters on many topics covered in this manual. It also 
explains the format and requirements for each system service. 


e The VAX/VMS I/O User's Guide discusses I/0 programming in 


detail, including chapters on several real-time devices. 


e The VAX/VMS Guide to Writing. a Device Driver ec eenate how _to 





on VAX/VMS I/O. 


The user's guide for each programming language provides information on 
using VAX/VMS features and capabilities with that language. 


The following handbooks provide information on VAX-11] architecture and 
hardware: 


@ The VAX-11 Architecture Handbook (order number EB-17580-18) 


introduces VAX-ll system architecture, explains addressing 
modes, and presents the native-mode instruction set. 





e The VAX~-11/780 Hardware Handbook (order number EB-17835-18) 
explains VAX-1l hardware elements, including the high-speed 
synchronous backplane interconnect (SBI), the central 
processor unit, intelligent console subsystem, MASSBUS and 
UNIBUS subsystems, main memory, and memory management. This 
handbook also includes an appendix explaining restrictions on 
program references to I/O space. 
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CONVENTIONS USED IN THIS DOCUMENT 


The system service formats and coding example conventions are 


consistent 
Manual: 
Convention 


UPPERCASE 


lowercase 


[ ] 


those used in the VAX/VMS System Services Reference 





Meaning 


Uppercase letters in a system service format show 
material that must be entered as shown. 


Lowercase letters in a system service format show 
variable data. 


Brackets in a system service format indicate an 
optional argument. 


Horizontal ellipsis in a coding example indicates 
that additional arguments necessary for the system 
service call but not pertinent to the example are 
not shown. 


Vertical ellipsis in a coding example indicates 


that lines of code not pertinent to the example 
are not shown. 
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CHAPTER 1 


INTRODUCTION 


"Real-time" is a term whose meaning varies with specific applications. 
However, in most scientific, industrial, and commercial real-time 
applications, one or both of the following are critical needs: 


e High throughput 
® Fast response 


Applications for which high throughput is essential require the 
continuous processing of large amounts of data. An example of a 
throughput-intensive application is signal processing, which is used 
in speech research, electrocardiogram and electroencephalogram 
research, vibration analysis, and music’ synthesis. As another 
example, a stream of data points is required for many of the 
qualitative and quantitative methods used in gas and liquid 
chromatography, mass spectrometry, automatic titration, and 
colorometry. 


In all of these throughput-intensive applications, the primary 
requirement is to obtain some number of data points equally spaced in 
time. Some further computation is done, perhaps later, on the data 
collected. 


In other real-time applications, fast response to individual events is 
the most critical requirement. A typical example that requires fast 
response is a closed-loop control system. In such a case, some event 
must be identified as soon as possible; a decision is then made and 
an output variable is updated. For example, before a jet engine is 
tested, sensing instruments connected to a processor running a control 
program might be placed on and near the engine. After the engine is 
started, the control program must be able to detect, analyze, and 
correct any abnormality within a few milliseconds ~- for instance, by 
shutting off the engine before an explosion occurs. Applications for 
which response time is a critical factor include process monitoring 
and control, synchronous communications, and stimulus-response testing 
in biological and psychological research. 


If response time iS critical, the designer must ensure that the 
application has all the resources it needs immediately whenever it 
needs them. These resources include; 


e cCPU time, the availability of which is affected by process 
priority and, perhaps, interrupt latency 


@ Memory, which can be controlled by several system services 
(see Chapter 2) 


e I/0 bandwidth, which is determined by the hardware 
configuration 
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These two real-time requirements, high throughput and responsiveness, 
are sometimes interrelated. For example, if your application must 
collect large amounts of data quickly and if the data acquisition is 
to be triggered by an external event, you need both fast response and 
high throughput. 


Specific real-time applications might involve the following types of 
programming activities: 


e Controlling the program's execution environment, which might 
require communicating between programs and creating 
subprocesses or detached processes 


e Using the Queue I/0 Request system service directly, to 
achieve faster response and greater throughput 


e Coordinating programs running on multiple processors, 
including the sharing of multiport memory units 


Real-time users often employ sophisticated means to make the system 
respond best to their special processing needs. The VAX/VMS system 
provides tools to meet these needs. 


1.1 REAL-TIME NEEDS AND VAX/VMS FEATURES 


From its inception, the VAX/VMS system has heen designed to meet the 
real-time processing needs of a wide user base. The VAX-11 
architecture provides the necessary hardware foundation with its high 
I/O bandwidth, interrupt responsiveness, 32-bit processing 
capabilities, and real-time peripheral interfaces. These 
architectural features are described in the hardware documentation for 
your system (see the Preface). This manual will focus on _ software 
features. Its approach is to identify functions common to a variety 
of real-time applications, discuss these functions conceptually, and 
Show how specific VAX/VMS features can be used to perform these 
functions, 


You are assumed to be familiar with basic VAX/VMS concepts, which are 
defined in the VAX/VMS_ Summary Description and Glossary. Do not, 
however, confuse the VAX/VMS term “process" (the program image and the 
software context in which it executes) with "process" in its generic 
sense (a sequence of events), aS in “industrial process~-control 
applications." Most instances of the word "process" in this manual 
refer to the image and its context; any other use will be clearly 
identified. 





Table 1-1 summarizes common real-time needs and the features or 
capabilities available with VAX/VMS to meet these needs. Each feature 
listed is documented in the VAX/VMS System Services Reference Manual 
unless another manual is specified. The goal of the present manual is 
to organize and highlight aspects of special interest to real-time 
users. 
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Table 1-1 
Real-Time Needs -and VAX/VMS Features 


VAX/VMS Feature 





Real-Time Need 











Perform an operation Use the Create Process (SCREPRC) 
with or after another service to create a subprocess or 
operation detached process 

Use the RUN’ command to create a 


subprocess or detached process (see the 








Change the availability Use the Set Priority (SSETPRI) service 
of a process for 
scheduling 


Keep critical code or Use the Adjust Working Set (SADJWSL) 

data highly accessible system service to adjust the amount of 
physical memory a process is entitled to 
use 


Use the Lock Pages in Memory (SLCKPAG) 
system service to keep pages in physical 
memory 


Use the Lock Pages in Working Set 
(SLKWSET) system service to keep pages 
in physical memory as long as the 
process is in memory 





Use the Set Process Swap Mode (SSETSWM) 
system service to keep all or part of a 
process in physical memory 


Use the Create and Map Section (SCRMPSC) 
system service to map a file into 
process address space 


Perform I/O quickly or Use the Queue I/O Request (SQIO) 
for special purposes system service 





Map 1/0 space (using the SCRMPSC 
service) and/or connect to a device 
interrupt vector (using the SQIO 
service) 


Write your own device driver (see the 
VAX/VMS Guide to Writing a_ Device 





Driver) 
Synchronize a process Set and wait for event flags 
with an external event 
or program Code and declare asynchronous system 


trap (AST) service routines 
Connect to a device interrupt vector 


Cause processes to hibernate or suspend, 
and to awaken when needed 








(continued on next page) 
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Table l-1 (Cont. ) 
Real-Time Needs and VAX/VMS Features 







Real-Time Need VAX/VMS Feature 








Share code or data Use the Create and Map Section 
between processes (SCRMPSC) system service to create and 
map a global section 


Use shareable images (see the VAX-11 
Linker Reference Manual) 





Send messages to other Use mailboxes (SCREMBX system service 
processes creates mailbox; RMS or I/O system 
services read and write messages) 


Use multiport memory Use common event flag clusters, global 
(memory shared by sections, and mailboxes located ina 
multiple processors) shared memory unit 


Use special-purpose Write privileged shareable images 
system services (see Chapter 6) 











1.2 OTHER VAX/VMS TOOLS 


There are other VAX/VMS tools which may be of interest to some 
real-time users, but which are outside the scope of this manual. 
Brief descriptions of these tools follow, with references to other 
manuals for detailed information. 


1.2.1 Condition Handling 


A condition handler is a procedure that is given control when an 
exception occurs. An exception is an event that is detected by the 
hardware or software and that interrupts the execution of an image. 
Examples of exceptions include arithmetic overflow or underflow and 
reserved opcode or operand faults. 


If you want to handle any or all exceptions yourself, you must code 
and declare a condition handler. Information on condition handling is 
available in the VAX/VMS System Services Reference Manual, the VAX-11l 
Run-Time Library Reference Manual, and the language user's guides, 











1.2.2 Device Allocation 


You can allocate and deallocate devices from within your program with 
the Allocate Device (SALLOC) and Neallocate Device (SDALLOC) system 
services. Allocating a device reserves it for exclusive use by the 
requesting process. The VAX/VMS System Services Reference Manual 
explains the SALLOC and SDALLOC system services. 
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1.2.3 SYSGEN Parameter Selection 


There are a number of parameters to the SYSGEN utility whose values 
affect the paging, swapping, and scheduling operations of the system. 
All of these parameters have default values that DIGITAL has’ selected 
as suitable for a wide range of users; however, real-time users may 
wish to modify certain parameters or experiment with different 
combinations of parameters. The VAX/VMS System Manager's Guide 
discusses major SYSGEN parameters and provides some guidelines for 
selecting their values. That manual also discusses a number of 
parameters in relation to system tuning. 





1.2.4 User Authorization File Entries 


The user authorization file (SYSUAF.DAT) includes entries within each 
record to determine the base priority (PRIORITY), initial working set 
limit (WSDEFAULT), maximum working set limit (WSQUOTA), and privileges 
for that user's processes. The VAX/VMS System Manager's Guide 
explains the user authorization file entries. 





1.2.5 Networks 


A VAX/VMS system can be connected in a communications network to other 
DIGITAL processors with the same or different operating systems. The 
family of software products supporting these networks is called 
DECnet. You can use DECnet to share files and communicate hetween 
programs on different processors; however, for faster performance you 
can use one of the real-time devices mentioned in Section 1.3. For 
information on the use of DECnet, see the DECnet-VAX User's Guide and 
the DECnet-VAX System Manager's Guide. 








1.3 REAL-TIME DEVICES 


The following devices are especially suited for real-time 
applications: 


e Laboratory Peripheral Accelerator (LPA11-K) 

@e Parallel Communications Link (PCL) 

e 32-bit Parallel SBI Interface (DR780) 

e Synchronous Communications Line Interface (DMC11) 

e Multiport Memory (MA780) 
This section discusses several of these devices only briefly. For 
detailed information on using the MA780, see Chapter 5, For 


information on the other devices, see the VAX/VMS I/O User's Guide and 
the appropriate hardware documentation. 





The LPAl1-K controls analog~-to-digital (A/D) and digital-to-analog 
(D/A) converters, digital I/0 registers, and real-time clocks. 
Appendix B discusses programming and design considerations for LPA11-K 
users. 


The DR780 can be used to link uSer devices to a processor or 


processors to each other. The DR780 provides a very high-speed 32-bit 
wide interface to the VAX-11 Synchronous Backplane Interconnect (SBI). 
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The DMC1l1l and the MA780 are used primarily to link processors. The 
MA780 offers memory-access speed and greater capabilities, but the 
DMC11 is suited for data transmission between processors separated by 
a great distance. The DIGITAL Data Communications Message Protocol 
(DDCMP) programmed into the DMCll's microprocessor ensures data 
integrity. 


1.4 USER PRIVILEGES FOR REAL-TIME APPLICATIONS 


To protect the integrity of the system, VAX/VMS' restricts certain 
functions or operations to processes with the appropriate user 
privileges. Each process starts with a set of privileges established 
in one of the following ways: 


e For each user who logs in, privileges are designated by the 
system manager in the user's entry in the user authorization 
file. 


@ For each created process, privileges are specified or 
defaulted in the PRVADR argument to the Create Process 
(SCREPRC) system service or the /PRIVILEGES qualifier to the 
RUN command. 


You can change a process's privileges in two ways: at the command 
level with the SET PROCESS/PRIVILEGES command and at the program level 
with the Set Privileges (SSETPRV) system service. 


Most timesharing users need and are given only a limited set of 
privileges. Real-time users, however, are normally given considerably 
more privileges, because they need them to perform certain functions. 
Any privileges required for functions discussed in this manual are 


Some of the privileges of special interest to real-time users are as 
follows: 


Privilege Meaning 
ALTPRI Set process base priority higher than user's own base 
priority 
BYPASS Bypass all UIC-based protection checks 
CMEXEC Change mode to executive 
CMKRNL Change mode to kernel 
EXQUOTA Exceed certain quotas 
GROUP Control processes in user's own group 
GRPNAM Place entries in group logical name table 
LOG IO Perform logical I/O operations 
OPER Perform operator functions 
PFNMAP Map to section by physical page frame number 
PHY IO Perform physical I/0 
PRMCEB Create permanent common event flag clusters 
PRMGBL Create permanent global sections 
PRMMBX Create permanent mailboxes 
PSWAPM Change process swap mode 
SETPRV Grant process privileges other than = own current 
privileges 
SHMEM Perform certain functions in memory shared by multiple 
processors 
SYSNAM Place entries in syStem logical name table and create 
system-wide global sections 
SYSPRV Access reSources as if you have a_=e system user 
identification code (UIC) 
WORLD Control any process in the system 
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The VAX/VMS System Manager's Guide explains these and the other 
privileges in greater detail. 





1.4.1 Privilege Masks 


User privileges are stored in a quadword (44-bit) mask, in which 
specific bits correspond to specific privileges. The operating system 
actually maintains four separate privilege masks for each process: 


e AUTHPRIV - Privileges that the process is authorized to 
enable, as designated by the system manager or the process 
creator. The AUTHPRIV mask never changes during the life of 
the process. 


@ PROCPRIV - Privileges that are designated as permanently 
enabled for the process. The PROCPRIV mask can be modified by 
the Set Privileges (S$SETPRV) system service or the SET 
PROCESS/ PRIVILEGES command. 


e@ IMAGPRIV - Privileges that the current image is installed 
with. 


@ cCURPRIV - Privileges that are currently enabled. The CURPRIV 
mask can be modified by the Set Privileges (S$SETPRV) system 
service or the SET PROCESS/PRIVILEGES command. 


When a process is created, its AUTHPRIV, PROCPRIV, and CURPRIV masks 
have the same contents. Whenever a system service must check the 
process's privileges, it checks the CURPRIV mask. When a process runs 
a known image, the privileges that the image was installed with are 
enabled in the CURPRIV mask. Whenever an image exits, the PROCPRIV 
mask is copied to the CURPRIV mask. 


1.5 PROCESS QUOTAS 


To prevent a process from monopolizing or overusing certain resources, 
VAX/VMS enforces a number of quotas (limits) on each process. These 
quotas can be adjusted for each process. The system manager can set 
quotas for each user in the user authorization file (UAF), and the 
creator of a detached process or subprocess can specify quotas with 
the QUOTA argument to the Create Process (SCREPRC) system service (see 
Section 2.1.3) or with qualifiers to the RUN command (see Section 
2.1.4). Default values are used for any quotas not specified. 


Each quota is deductible, pooled, or nondeductible: 


e A deductible quota value is subtracted from its creator's 
current value when a subprocess is created and returned to the 
creator when the subprocess is deleted. 


e A pooled quota is shared by a detached process and all its 
descendent subprocesses. Charges against a pooled quota value 
are subtracted from the current available total as_ the 
resource is used and are added back to the total when the 
resource is not being used. 


e A nondeductible quota is established and maintained separately 
for each detached process and subprocess. 


The VAX/VMS System Services Reference Manual contains more detailed 


> erga Me ae ee eee 
information on process quotas. 





INTRODUCTION 




















Table 1-2 lists each process quota, its function, the defaults used 
for the user authorization file (UAF) and for process creation, and 
the minimum value. The table also indicates whether the quota is 
deductible, pooled, or nondeductible. 
Table 1-2 
Summary of Process Quotas 
—-— 
UAF Process 
Default}Creation 
Functionl Value Default 
AST queue Limits the sum of ASTs and 10 6 
limit (ASTLM) scheduled wake-up requests that 
can be pending for a process at 
one time (N) 
Buffered I/O count |Limits the number of I/0 oper- 6 6 
limit (BIOLM) ations that the process can have 
buffered in system memory (N) 
Buffered I/O byte Limits the number of bytes that 4095 8192 
count limit (BYTLM)|the process can use for system 
buffered I/O operations (P) 
CPU time limit CPU time limit in milliseconds 0 0 
(CPUTIME) (O means no limit) (D) 
Direct I/O count Limits the number of I/O oper- 6 6 
limit (DIOLM) ations that the process can have 
buffered in process address 
space (N) 
Open file limit Limits the number of files that 20 10 
(FILLM) the process can have open at. one 
time (P) 
Paging file Limits the number of pages that 10000 2048 
quota (PGFLQUOTA) the process can use in the system 
paging file (P) 
Subprocess creation|Limits the number of subprocesses| 8 8 
limit (PRCLM) that the process can create (P) 
Timer queue entry Limits the sum of timer queue 10 8 
limit (TQELM) entries and temporary common 
event flag clusters that the 
process can have at one time (P) 
Default working set;/Sets the initial working set 150 100 
size (WSDEFAULT) size for the process (N) 
Working set size Limits the size to which the 200 120 
limit (WSQUOTA) process's working set size can 
be expanded (N) a 
l. After each "Function" description is a letter in parentheses 
indicating whether the quota is deductible (D), pooled (P), or 











nondeductible (N). 
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1.5.1 Resource Wait Mode 


By default, a process enters resource wait mode whenever it needs but 
cannot obtain system dynamic memory or a resource controlled by any of 
the following quotas: 


e® Direct I/O limit (DIOLM) 
e Buffered I/O limit (BIOLM) 
e Buffered I/O byte count limit (BYTLM) 


(If any other resource controlled by a quota is unavailable, the 
process receives the SS$_EXQUOTA error status code.) Resource wait 
mode places the process in a wait state until the resource’ becomes 
available. 


In a real-time environment, however, it may not be practical or 
desirable for a program to wait. In these cases, you can choose to 
disable resource wait mode for the process, so that when a_e required 
resource is unavailable, control returns immediately to the calling 
program with an error status code. You can disable resource wait mode 
with the Set Resource Wait Mode (SSETRWM) system service. 


How a program responds to the unavailability of a resource depends 
very much on the application and the particular system service that is 
being called. In some instances, the program may be able to continue 
execution and retry the service call later. In other instances, it 
may be necessary only to note that the program is being required to 
wait. 


1.6 PROCESS PRIORITY 


At any given time, each process has a priority that affects how it 
runs relative to other processes in the system, Process priorities 
can range from 0 through 31, with O through 15 designated as 
timesharing priorities and 16 through 31 designated as real-time 
priorities. 


The “base priority" of a process refers to its minimum priority. You 
can adjust a process's base priority with the Set Priority system 
service or the SET PROCESS/PRIORITY command. The priority that 
affects process operations is its current priority (or simply, 
priority), which the system dynamically adjusts for timesharing 
processes. 


The system handles timesharing and real-time priorities in different 
ways. For processes with timesharing base priorities (0 through 15), 
the system dynamically adjusts the priority according to the process's 
state and other factors. The actual priority of a timesharing process 
at any given time might be as much as 7 higher than its base priority. 
However, the system will never raise a priority in the timesharing 
range to a real-time level. Furthermore, the system does not alter 
the priority of a process with a real-time hase priority (16 through 
31). 
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When you log in, your initial base priority is determined by a value 
in your record in the user authorization file. When you create a 
subprocess or detached process, its initial base priority is 
determined by the specified or default value for the BASPRI argument 
to the Create Process (SCREPRC) system service or for the /PRIORITY 
qualifier on the RUN command. To find out the base priority of your 
process, you can use the SHOW PROCESS command. 


1.6.1 Significance of Process Priority 
The priority of a process can affect 


e How quickly it is scheduled (that is, becomes the current 
process) after it becomes executable 


e Whether it will be interrupted by the scheduling of another 
process 


e Whether it will be swapped out of the balance set if the 
system needs the physical memory for another process 


e How quickly its queued I/O requests are serviced by a device 
driver 


The VAX/VMS scheduler always selects the highest-priority process from 
among those that are eligible to execute, that is, processes that are 
"computable" (process state) and in the balance set. (Conditions that 
can cause a process not to be executable include waiting for an event 
flag to be set or a resource to become available, or being in a_ state 
of hibernation or suspension.) If a Mlower-priority process is 
executing and a higher-priority process becomes executable, the 
lower-priority process is interrupted and the higher-priority process 
receives control of the processor. 


If the working set requirements of all processes in the balance set 
exceed the system's available physical memory, the VAX/VMS swapper 
process is activated to "outswap" one or more processes: that is, to 
Save certain information and the working set of each process to be 
Swapped out and to free its memory pages for use by other processes. 
A real-time process requiring fast response, however, should not he 
swapped out. In selecting a process for outswapping, VAX/VMS 
considers the process's state and quantum value in addition to its 
priority. Therefore, if you must guarantee that a real-time process 
will not be swapped out, disable swapping for the process with the Set 
Process Swap Mode (SSETSWM) system service (see Section 2.2.4). 


The VAX/VMS system also uses process priority as the basis’ for 
ordering I/0 requests queued to a driver. That is, the system 
initiates a queued I/O request issued by a higher-priority process 
before it initiates one for the same device issued by a lower-priority 
process. 


Because the VAX/VMS operating system's own processes normally have 
priorities of 16 or lower, real-time users must ensure that one of 
these system processes is not blocked from execution if its operation 
is needed by a real-time process. For example, if several real-time 
processes are in the system, a priority-22 process performing disk 
file I/O can be blocked by a compute-bound priority-17 process that is 
preventing the disk ACP (which might be priority 11) from executing. 
If an operating system process needs to perform functions for a 
real-time process, you might have to raise the priority of the 
System's process. 
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1.6.2 Adjusting the Base Priority 


Raising process priority can decrease the time required for a program 
to run to completion. Programs running in real-time processes have 
more predictable execution times, because the process usually waits 
only for the completion of requests that it initiates; it does not 
spend time wating for lower-priority processes to execute. 


The higher the process's priority is set, the less likely it is the 
process will have to wait. However, you must use discretion in 
raising priorities, because as you increase the number of real-time 
processes executing concurrently, you potentially decrease the 
effectiveness of each priority designation. 


User privileges are required to set the priority of any process’ other 
than your own or to raise the priority of any process (including your 
own) higher than your own base priority. The following user 
privileges enable you to perform the indicated functions: 


e The GROUP privilege allows you to change the priority of other 
processes in your group. 


e The WORLD privilege allows you to change the priority of any 
other processes in the system. 


e The ALTPRI privilege allows you to set the priority of any 
process whose priority you have privilege to change (see GROUP 
and WORLD privilege explanations) higher than your own base 
priority. If you do not have the ALTPRI privilege, you can 
set the priority of any process whose priority you have 
privilege to set only equal to or lower than your own base 
priority. 


There are two ways to change the base priority of a process: 
@ At the command level with the command: 
S$ SET PROCESS/PRIORITY=n 


@ At the program level with the Set Priority (S$SETPRI) system 
service 


The Set Priority system service is probably more useful to real-time 
programmers than the SET PROCESS/PRIORITY command, because the system 
service enables you to set process base priorities dynamically 
according to the program's logic. This service has the following 
general formats: 
MACRO Format 

SSETPRI [pidadr],[prenam],pri, [prvpri] 
High-Level Language Format 

SYSSSETPRI ({pidadr], [prcnam],pri, [prvpri]) 


The VAX/VMS System Services Reference Manual has a detailed 
explanation of the Set Priority system service. 
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CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT 


The VAX/VMS system gives you considerable control over the execution 
context of your applications, provided you have suitable user 
privileges. Each application runs in the context of one or more 
processes and can control that context in the following ways: 


e Create processes (subprocesses or detached processes) to 
divide the work into related segments 


e Set each process's base priority to achieve real-time 
responsiveness 


e Control each process's use of physical memory 


You can use these features to ensure that all components of a 
real-time application receive adequate processor time and physical 
memory when they need them. 


Process base priority is discussed in Section 1.6. Process creation 
and control of physical memory are discussed in this chapter. 


The DISPLAY utility allows you to monitor system activity, and thus to 
obtain information that can guide you in using features discussed in 
this chapter. The VAX/VMS System Manager's Guide explains the 
functions and operation of the DISPLAY utility. 





The Get Job/Process Information (SGETJPI) system service can also be 
used to obtain information about one or more processes. The VAX/VMS 
System Services Reference Manual explains’ the Get Job/Process 
Information system service, including the "wild card" process 
searching capability. 





2.1 PROCESS CREATION 


Real-time applications are often divided into a number of programs. 
Each program might run concurrently with one or more others, and each 
might run conditionally (for example, only when certain events occur). 


The VAX/VMS system allows you to create processes to run these 
programs, These created processes can be subprocesses or detached 
processes, depending on your purpose and user privileges. 


You can create either type of process with the Create Process 
(SCREPRC) system service or with the RUN command, although real-time 
applications frequently create subprocesses with the SCREPRC system 
service and detached processes with the RUN command (often within a 
command procedure at the start of the application). Section 2.1.3 
discusses the SCREPRC system service, and Section 2.1.4 discusses the 
RUN (Process) command. 
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2.1.1 Subprocesses and Detached Processes 


Subprocesses and detached processes are treated the same by the 
scheduling and swapping components of the operating system. For 
example, each process of either type has a base priority that the 
system uses in scheduling processes, allocating CPU time, and deciding 
which process to swap out if necessary. Both types of process are 
shown in the displays generated by the SHOW SYSTEM command and the 
DISPLAY utility. 


Subprocesses and detached processes differ, however, in their degree 
of independence from their creator and in the privileges and quotas 
required to use them. Table 2-1 summarizes the major differences 
between a subprocess and a detached process. 


Table 2-1 
Subprocess versus Detached Process 








Subprocess Detached Process 











Has own resources and 
quotas 


Shares creator's resources 
and its deductible and 
pooled quotas 


Must terminate before its 
creator; automatically 
terminated when its 
creator is deleted 


Termination is independent 
of its creator's 


DETACH privilege required 
to create a detached 
process 


No privilege required to 
create a subprocess 


Number of subprocesses 
is limited by creator's 
PRCLM quota 


Number of detached proces- 
ses is limited only by the 
system's maximum total 
process count (SYSGEN 
parameter MAXPROCESSCNT) 


Must allocate devices it 
needs to reserve for 
exclusive use 


Can access devices allocated 
by its creator 








A process does not need GROUP privilege to use system services or 
commands that affect any subprocess it creates (for example, to change 
the subprocess's priority). A process does need GROUP or WORLD 
privilege, however, to affect a detached process (GROUP if the 
detached process is in its group, otherwise WORLD). 
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2.1.2 Real-Time Uses of Detached Processes and Subprocesses 


Real-time applications often create detached processes to perform 
highly privileged functions and subprocesses’ to perform functions 
requiring little or no privilege. Isolating privileged code as a 
detached process makes it easier to debug and affords greater 
protection for the system as a whole. Once it is created, a detached 
process is more insulated than a subprocess from any errors its 
creator may incur, because a detached process terminates independently 
of its creator's termination, whereas a subprocess is automatically 
deleted under the following conditions: 


e If the subprocess was created by a process that is using the 
command interpreter (for example, by the process created for 
you at login time), the subprocess is deleted when its 
creating process logs out. 


e If the subprocess was created by a process that is not using 
the command interpreter (for example, by another subprocess or 
a detached process executing a single image), that subprocess 
is deleted when its creator is deleted. 


A process can explicitly delete itself or, if it has suitable 
privilege, another process by using the Delete Process (SDELPRC) 
system service. The WORLD privilege allows you to delete any process 
in the system; the GROUP privilege allows you to delete other 
processes in your own group. 


2.1.3 Create Process System Service 


The Create Process (SCREPRC) system service gives you program-level 
control over the creation of subprocesses and detached processes. For 
example, you might simply create a process at the beginning of the 
program and control that created process's activity through the 
hibernation or suspension mechanisms (see Chapter 3). On the other 
hand, you might need to test values within your program or wait for 
some external event before creating another process. In any case, 
process creation is relatively time consuming, and therefore should be 
used prudently in real-time programs,. 


The Create Process system service has the following general formats: 
MACRO Format 


SCREPRC [pidadr], [image], [input], [output], [error], 
[prvadr], [quota], [prcnam], [baspri], [uic], 
{mbxunt], [stsflg] 


High-Level Language Format 


SYSSCREPRC ([pidadr], {image], [input], [output], [error], 
[prvadr], [quota], [prcenam], [baspri], [vic], 
[mbxunt], [stsf1lg]) 


The following arguments to SCREPRC are of special interest to 
real-time users: 


@ UIC - Determines whether the created process is a _ subprocess 
(no UIC specified -- UIC same as creator) or a detached 
process (UIC specified). 
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e PRVADR - Allows you to specify privileges for the created 
process. To give the created process any privilege the 
creator does not have, you must have the SETPRV privilege. 


e BASPRI - Allows you to specify a base priority for the created 
process. To assign the created process a base priority higher 
than the creator's own, you must have the ALTPRI privilege. 


e STSFLG - Allows you to specify various options for the created 
process. 


For a detailed explanation of the Create Process system 
the VAX/VMS System Services Reference Manual. 


service, see 





2.1.4 RUN (Process) Command 
The RUN command creates a subprocess or detached process to run a 
specified program if you enter any of the process-related command 
qualifiers (that is, any qualifier other than /DEBUG or /NODEBUG). 
The general format for the RUN command to create a subprocess or 
detached process is listed as follows: 

$ RUN/command-qualifiers program-file-spec 
Each of the process-related command qualifiers is optional, although 
you must enter at least one. The presence of the /UIC command 
qualifier determines whether the created process is a detached process 
(qualifier specified) or a subprocess (qualifier not specified). The 
process-related command qualifiers and their default values are listed 
below. 


Qualifier 


/ (NO] ACCOUNTING 

/AST LIMIT=quota 

/ [(NOTAUTHORIZE 

/BUFFER LIMIT=quota 
/DELAY=delta time 
/ERROR=file-spec 
/FILE_LIMIT=quota 
/INPUT=file-spec 
/INTERVAL=delta-time 
/10_BUFFERED=quota 
/TO_DIRECT=quota 
/MAILBOX=unit 

/MAXIMUM WORKING SET=quota 
/OUTPUT=File-spec 
/PRIORITY=n 
/PRIVILEGES=privilege-list 
/PROCESS NAME=process-name 
/QUEUE LIMIT=quota 
/{NO]RESOURCE WAIT 
/SCHEDULE=absolute-time 
/{NO]SERVICE FAILURE 
/SUBPROCESS LIMIT=quota 

/ {NO] SWAPPING 

/TIME LIMIT=limit 

/UIC=uic 

/WORKING SET=default 


Default (if applicable) 


/ACCOUNTING 
10 (outstanding ASTs) 


10240 (bytes) 
20 (files) 


5 (outstanding requests) 
6 (outstanding requests) 


200 (pages) 


(same as creator) 

(same as creator) 

(null name) 

8 (outstanding timer queue requests) 
/RESOURCE WAIT 


/NOSERVICE FAILURE 

8 (subprocesses) 
/SWAPPING 

0 (that is, no limit) 


200 (pages) 
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The /UIC, /PRIVILEGES, and /PRIORITY qualifiers serve the same 
purposes as the UIC, PRVADR, and BASPRI- arguments to the Create 
Process system service (see Section 2.1.3). 


The VAX/VMS Command Language User's Guide has a complete explanation 
of the RUN command and the process-related qualifiers. 





You may want to include RUN commands for process creation in command 
procedures. The following example showS a command procedure that 
prompts for information and then creates a subprocess. 


SINQUIRE DEVICE "Device name" 'Specify input device 

SINQUIRE TEST "Test name" . {Specify program to be run 

SINQUIRE INTERVAL "How often should it be reported? (O:mm:ss)" 

SRUN/PROCESS NAME='TEST'/PRIORITY=19/INPUT='DEVICE' /OUTPUT=OPA0 :- 
/INTERVAL='INTERVAL ! 'TEST! 


2.2 PHYSICAL MEMORY CONTROL 


Physical memory is one of the most valuable system resources to a 
real-time user. Programs execute faster when the code and data they 
need at any given instant are already in memory and do not need to he 
retrieved from disk storage. 


In brief, VAX/VMS memory management operates in the following way. 
The pages of a process that are currently in physical memory (usually 
a subset of all the process's pages) constitute that process's working 
set. The maximum number of physical memory page frames a process can 
occupy is determined by its current working set limit. When the 
number of page frames in use reaches the working set limit and the 
process needs additional pages, the system pages the process against 
itself. That is, the system releases pages in the working set 
(placing each one on the free page list or the modified page list) and 
then reads the pages it needs from disk or finds them in memory (on 
the free page list or the modified page list). If and when the 
working set requirements of all processes in the balance set (that is, 
processes currently in memory) exceed the available physical memory, 
one or more lower-priority processes are swapped out (temporarily 
removed from the balance set) and their page frames are made available 
for use by other processes. For more detailed information on VAX/VMS 
memory management, see the VAX/VMS Summary Description and Glossary or 
the VAX-11/780 Technical Summary. For information on parameters to 
the SYSGEN utility affecting memory management, see the VAX/VMS System 
Manager's Guide. 








Several system services allow you to control the operating system's 
allocation of physical memory to the process. The following services 
are most pertinent to real-time manipulation of physical memory: 

e Adjust Working Set Limit (SADJWSL) 

e Lock Pages in Memory (SLCKPAG) 

e Lock Pages in Working Set (SLKWSET) 

e Set Process Swap Mode (SSETSWM) 
The subsections that follow give brief descriptions and general 


formats for these services, For more detailed information, see the 
VAX/VMS System Services Reference Manual. 
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2.2.1 Adjusting the Working Set Limit (SADJWSL) 


The Adjust Working Set Limit (SADJWSL) system service allows you to 
increase or decrease the maximum number of physical memory pages your 
process can occupy. You can also use this system service to find your 
current working set limit. (You can change and find out your working 
set limit at the command level with the SET WORKING SET and SHOW 
WORKING SET commands.) 2 


The VAX/VMS system normally performs automatic working set adjustment. 
However, automatic working set adjustment is inhibited for all 
processes if you specified WSINC=0 to the SYSGEN utility, and 
automatic working set adjustment is inhibited for a given process if 
the process has a real-time priority (16 through 31) or if the 
process's working set default value is equal to its working set quota 
(maximum) value. The VAX/VMS System Manager's Guide explains 
automatic working set adjustment and the SYSGEN parameters that affect 
its operation. 





One of the simplest forms of memory management is to change the 
working set limit at different points in your program. Large programs 
usually proceed in phases; for example, a program might perform a 
heavily IT/O-bound setup phase, then settle into localized 
compute-bound processing, then do discontiguous array processing, and 
so forth. If your code has definable phases, you may want to call the 
SADJWSL system service at logical points to increase or decrease the 
working set limit. 


Another use of this system service is to prevent the excessive paging 
activity that occurs when a program runs in too small a working set. 


You should avoid excessive use of this system service, however, 
because it incurs overhead for your process and perhaps for other 
processes in the system. 


No user privilege is required to use the SADJWSL system. service. 
However, you cannot set a process's working set limit lower than the 
system's minimum limit (determined by the SYSGEN parameter MINWSCNT) 
or higher than the process's maximum working set size (determined by 
its WSQUOTA entry in the UAF or specified when the process was 
created). 


The Adjust Working Set Limit system service has the following general 
formats: 


MACRO Format 
SADJWSL [pagent], [wsetlm] 
High-Level Language Format 


SYSSADJWSL ( [pagent], [wset1m]) 


2.2.2 Keeping Pages in the Working Set ($LKWSET) 


The Lock Pages in Working Set ($LKWSET) system service allows you to 
specify that a page or range of pages should not be replaced in the 
working set, perhaps because these pages are heavily used or because 
the code in them must gain control and execute quickly whenever it is 
needed. If the specified pages are not already in the working set, 
they are brought into memory if necessary and locked in the working 
set. Pages locked in the working set remain so until they are 
unlocked by the Unlock Pages from Working Set (SULWSET) system 
service. 
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Pages locked in the working set can be removed from physical memory, 
however, if their process is swapped out (that is, if the process's 
working set is removed from the balance set). To prevent this from 
happening, use the Set Process Swap Mode (SSETSWM) system service to 
disable swapping (see Section 2.2.4). 


Locking pages in the working set is normally sufficient to guarantee 
that their contents are accessible, especially if swapping is disabled 
for the process. However, in a few cases you may need to lock the 
pages in memory using the Lock Pages in Memory (SLCKPAG) system 
service (see Section 2.2.3), to guarantee that the physical location 
of the contents never changes. These cases include the following: 


e The process must lock pages for a routine that will execute at 
an elevated interrupt priority level (IPL). Section 4.4.1 
discusses interrupt priority levels. 


e The process is not using the VAX/VMS I/O system and must lock 
pages for direct I/0 operations. 


If you use the SLKWSET system service, be careful not to lock so many 
pages that the remaining pages in the working set incur too many page 
faults. If excessive page faulting occurs, you may need to increase 
the working set limit with the Adjust Working Set Limit (SADJWSL) 
service (see Section 2.2.1). 


The Lock Pages in Working Set syStem service has the following general 
formats: 


MACRO Format 
SLKWSET inadr, [retadr}, [acmode] 
High-Level Language Format 
SYSSLKWSET(inadr, {retadr], facmode]) 


The general format of the Unlock Pages from Working Set system service 
is the same as the above, except that SULWSET or SYSSULWSET is used 
instead of SLKWSET or SYSSLKWSET. 


2.2.3 Keeping Pages in Memory (SLCKPAG) 


The Lock Pages in Memory (S$LCKPAG) system service locks a virtual page 
or range of virtual pages in physical memory. If the specified 
virtual pages are not already in memory, they are brought into’ the 
working set and then locked in memory. Locked pages are not available 
for page replacement until they are unlocked by the Unlock Pages from 
Memory (SULKPAG) system service or until the program terminates 
(locked pages are unlocked automatically at image exit). You must 
have the PSWAPM user privilege to lock pages in memory. 


It is usually not necessary to lock pages in memory; locking them in 
the working set is often sufficient. (Section 2.2.2 discusses cases 
in which pages should be locked in memory.) Use caution, however, 
because locking any pages in memory reduces by that number the pages 
that VAX/VMS memory management can allocate among other processes in 
the system. : 
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Locked pages remain in memory even if their process is swapped out. 
To prevent the process from being swapped out, use the Set Process 
Swap Mode (SSETSWM) system service to disable swapping (see Section 
2.2.4). 


The Lock Pages in Memory system service has the following general 
formats: 


MACRO Format 
SLCKPAG inadr, [retadr], [acmode] 
High-Level Language Format 
SYSSLCKPAG (inadr, [retadr], [acmode]) 


The general format of the Unlock Pages in Memory system service is the 
same as the above, except that SULKPAG or SYSSULKPAG is used instead 
of SLCKPAG or SYSSLCKPAG. 


2.2.4 Keeping the Process in Memory (SSETSWM) 


The Set Process Swap Mode (SSETSWN) system service enables you to 
prevent your process from being swapped out of memory or to allow it 
to be swapped out of memory. You. must have the PSWAPM user privilege 
to alter process swap mode. 


An example of real-time use of setting process swap mode is a process 
running an image that must respond quickly to some external event 
(such as an interrupt), but has nothing to do until the event occurs. 
After it is activated, the image can lock critical pages in its 
working set (see Section 2.2.2), disable swapping for the process, and 
hibernate. (It is important to disable swapping, because being in a 
hibernate state normally makes a process a good candidate for 
outswapping.) When the event occurs, an AST service routine (see 
Section 3.3) can awaken the process. 


The Set Process Swap Mode system service has the following general 
formats: 


MACRO Format 
SSETSWM [swpflg] 
High-Level Language Format 
SYSSSETSMW ([swpflg]) 


The SWPFLG argument can be a value of 0 (the default, to allow 
swapping) or 1 (to inhibit swapping). 


CHAPTER 3 


COMMUNICATING AND SHARING BETWEEN PROCESSES 


Real-time applications often consist of related programs running as 
several processes. These processes may be detached processes, or they 
may be a detached process with one or more subprocesses. These 
processes usually need to communicate with each other and to share 
common code or data. Interprocess communication often consists of 
event notification (for example, that an I/O operation is complete), 
although it can also involve transmission of messages or other data. 
Processes within the application can synchronize their operations 
through effective communication. Processes can alSo share code or 
data to reduce the application's physical memory requirements. 


Table 3-1 lists several VAX/VMS features that can be used to 
communicate between user processes, synchronize their operations, or 
share code and data. 


Table 3-1 
Features for Communication, Synchronization, and Sharing 









Feature Main Use 















Common event flags Notify process of event completion; 
synchronize access to a resource 


Mailboxes Pass messages or other data between 
processes 
AST service routines Execute desired routine in response to an 


external event, regardless of when the 
event occurs 


Hibernation and Activate subprocesses and detached pro- 


suspension cesses only when they are needed 
Global sections Share data or code 
Shareable images Share data or code 





Each feature listed in Table 3-1 is often used with one or more other 
features, For example, an AST service routine executing at I/0 
completion might write a message to a mailbox to be read by another 
process or might set an event flag for which another process is 
waiting. , 
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3.1 COMMON EVENT FLAGS 


Common event flags provide a simple and convenient means for’ event 
notification. Cooperating processes can set, clear, and wait for 
flags in a common event flag cluster. 


Common event flags can be used to synchronize access to a resource by 
multiple processes. Appendix A discusses and illustrates the use of a 
common event flag as a mutual exclusion (mutex) semaphore to lock a 
resource. 


Event flags are status~posting bits maintained by VAX/VMS for general 
programming use. Each process can manipulate up to 128 event flags, 
numbered 0 through 127. The event flags are grouped into four 
clusters of 32 flag bits each; however, whenever you set, clear, or 
wait for an event flag, you specify the flag number, not ae cluster 
number or name. (The significance of the cluster name for common 
event flag clusters is discussed later in this section.) 


The first two clusters, flags 0 through 31 and 32 through 63, are 
called local event flags because they are available only to a single 
process. Two additional clusters, flags 64 through 95 and 96 through 
127, are called common event flag clusters because they can be used by 
cooperating processes. Table 3-2 summarizes local and common event 
flag clusters. 


Table 3-2 
Summary of Event Flag Clusters 





















Event 
Flag Numbers Description Restriction 
0-23 Local event flag Event flags 24 
32-63 clusters for through 31 are 
general use by reserved for 
a process system use 
64-95 Common event Must be associated 
before use 


96-127 flag clusters 








Common event flag clusters are either temporary or permanent 
(depending on the PERM argument value in the Associate Common Event 
Flag Cluster system service call). 


Temporary common event flag clusters: 


e Do not require any Special user privilege, but do use part of 
the calling process's timer queue entries (TQELM) quota. 


e Are deleted when all processes associated with the cluster 
have disassociated from it. A process can disassociate 
explicitly using the Disassociate Common Event Flaq Cluster 
(SDACEFC) service, or it can disassociate implicitly at image 
exit. 
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Permanent common event flag clusters: 


e Require the creating process to have the PRMCEB user 
privilege. 


e Continue to exist until they are explicitly marked for 
deletion with the Delete Common Event Flag Cluster (SDLCEFC) 
service and no processes are associated with them. 


This section will present general formats and focus on aspects 
pertinent to real-time applications. Chapter 5 discusses special 
considerations for common event flag clusters in shared (multiport) 
memory. 





The VAX/VMS System Services Reference Manual has a chapter on event 
flag usage and detailed description of event flag services. 


3.1.1 Creating and Associating with Clusters 


To create or associate with a common event flag cluster, use the 
Associate Common Event Flag Cluster (SASCEFC) system service, which 
has the following general formats: 


MACRO Format 
SASCEFC efn,name, [prot], [perm] 
High-Level Language Format 
SYSSASCEFC (efn, name, [prot], [perm]) 


The first process specifying a given name creates the cluster and 
associates with it; any other processes specifying this name 
associate with the existing cluster. All processes associating with 
the same common event flag cluster must specify the same name, but 
they do not have to specify event flag numbers in the same 32-bit 
grouping. You can allow any other process in your group to associate 
with the cluster (the default) or restrict association to processes 
with your UIC (by specifying a PROT argument value of 1). You can 
make the cluster temporary (the default) or permanent (by specifying a 
PERM argument value of 1). 


3.1.2 Setting Event Flags 

You can set event flags in a variety of ways. The following system 
services accept an optional EFN argument, which specifies an event 
flag to be set when the operation is completed: 


e Queue I/O Request (SQIO and SQIOW forms, SINPUT and SOUTPUT 
macros) 


e Set Timer (SSETIMR) 
e Update Section File on Disk (SUPDSEC) 
e Get Job/Process Information (SGETJPI) 


Note that each of the above system services clears the specified event 
flag before it begins the requested operation. 
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You can also set an event flag using the Set Event Flag (SSETEF) 
system service. To clear an event flag, use the Clear Event Flag 
(SCLREF) system service. Both the $SETEF and SCLREF system services 


accept only one argument: EFN, a value indicating the flag to he set 


or cleared. 


3.1.3 Waiting for Event Flags 


If a process needs to be activated only in response to one or more 
events, you can use one of the following system services to place the 
process in a wait state until it must execute: 


e SWAITFR - The Wait for Single Event Flag system service places 
the process in a wait state until a single specified event 
flag has been set, 


e SWFLOR - The Wait for Logical OR of Event Flags system service 
places the process in a wait state until any one of a 
specified group of event flags has been set. 


e SWFLAND - The Wait for Logical AND of Event Flags system 
service places the process in a wait state until all of a 
specified group of event flags have been set. 


During this wait state the process can still receive asynchronous 
system trap (AST) interrupts, but after the AST service routine 
completes, the process automatically reexecutes the "Wait for..." 
service call. 


After the flag or flags have been set and the process has responded to 
the event(s), the process can reenter the wait state by looping back 
to the appropriate system service call. 


3.2 MAILBOXES 


A mailbox is a record~-oriented virtual I/0 device that cooperating 
processes can use to send mesSages, status information, return codes, 
or other data to each other. A mailbox must be created using the 
Create Mailbox and Assign Channel (SCREMBX) system service. Any other 
process that needs to use the mailbox simply assigns an I/O channel to 
the mailbox using the SCREMBX system service or the Assign I/O Channel 
(SASSIGN) system service. Actual data transfer (reading and writing) 
involving the mailbox is accomplished by using I/O system services, 
RMS, or high-level language I/O statements. 


Mailboxes are suited to sending messages that cannot be conveyed by 
the simpler and faster operations of setting and clearing event flags. 
Mailboxes can hold multiple messages, which are read on a first-in 
first-out (FIFO) basis, whereas with an event flag you cannot 
determine from a flag's current status how many times it has been set 
or cleared. Some overhead is involved, however, with the use of 
mailboxes. Therefore, to pass and read messages faster you can use a 
global section (see Section 3.5) to hold the messages and common event 
flags to notify processes that messages are ready to be read. 
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A special use of a mailbox is as a process termination mailbox, which 
receives a process termination message for the creating process when a 
subprocess or detached process is deleted. Process termination 
mailboxes are discussed in the VAX/VMS_ System Services Reference 
Manual. 





Mailboxes are either temporary or permanent. Table 3-3 contrasts the 
two types. 


Table 3-3 
Temporary versus Permanent Mailboxes 



























Temporary Permanent 
TMPMBX user privilege 1.  PRMMBX user privilege 
required to create required to create 
2. Creating process's buffered 2. No process quotas affected 
I/O byte count (BYTLM) 
quota is reduced (see 
Section 3.2.1) 
3. Logical name entered in 3. Logical name entered in 
group logical name table system logical name table 
4. Automatically deleted when 4. Must be explicitly marked 
no more channels are for deletion with the 


assigned to it Delete Mailbox (SDELMBX) 


service 





Chapter 5 discusses mailboxes in shared (multiport) memory. The 
chapter on the mailbox driver in the VAX/VMS I/O User's Guide contains 
information on the use of mailboxes and a programming example. 





3.2.1 Creating a Mailbox 

The Create Mailbox and Assign Channel system service creates a mailbox 
or, if the specified mailbox already exists, assigns a channel to it. 
This service has the following general formats: 


MACRO Format 


SCREMBX [prmflq],chan, [maxmsg], [bufquo], [promsk], 
[acmode], [lognam] 


High-Level Language Format 


SYSSCREMBX( [prmflg],chan, {maxmsg], [bufquo], (promsk], 
{acmode], [lognam]) 


The PRMFLG argument determines whether the mailbox is temporary (the 
default) or permanent (value of 1). If the mailbox is temporary, the 
process's buffered I/O byte count (BYTLM) quota is reduced by the sum 
of the following until the mailbox is deleted: 


e The number of bytes of system dynamic memory that can be used 
to buffer messages sent to the mailbox 


e The size of the mailbox unit control block 
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The PROMSK argument allows you to restrict access to the mailbox by 


setting specific bits in a protection mask. This mask contains four 
4~bit fields: 


15 11 7 3 0 
| vom | crow | one sre 


The bits are read from right to left in each field and indicate, when 
they are set, that read, write, execute, and delete access (in that 
order) are denied to the particular category of user. Only read and 
write access, however, are meaningful for mailbox protection. The 
default setting of 0 (ail bits cleared) indicates that all users have 
read and write access to the mailbox. 








The ACMODE argument allows a process executing at a more privileged 
access mode to associate a less privileged access mode with the 
channel assigned to the mailbox. (Kernel mode is the highest; user 
mode is the lowest.) The access modes and their corresponding values 
are listed below. The symbolic names for the values are defined by 
the SPSLDEF macro. 


Access Mode Value Symbolic Name 
Kernel 0 PSLSC_KERNEL 
Executive 1 PSL$C_EXEC 
Supervisor 2 PSLSC_SUPER 
User 3 PSLSC_USER 


Any ACMODE value you specify is maximized with your current access 
mode; that is, the channel is associated with the less privileged of 
the specified mode and your current mode. 


The LOGNAM argument allows you to specify the logical name associated 
with the mailbox. Processes using a mailbox must specify the same 
logical name to identify that mailbox. When the mailbox is created, 
the logical name is entered in the group logical name table if the 
mailbox is temporary and in the system logical name table if the 
mailbox is permanent. 


3.2.2 Other Mailbox Services 


To use an existing mailbox, your process must assign it an I/O channel 
using the Create Mailbox system service or the Assign I/O Channel 
system service. (A high-level language program, however, need only 
issue an OPEN statement specifying the logical name of the mailbox.) 
The Assign I/O Channel system service has the following general 
formats: 
MACRO Format 

SASSIGN devnam,chan, [acmode], [mbxnam] 
High-Level Language Format 


SYSSASSIGN (devnam, chan, [acmode], [mbxnam]) 
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The DEVNAM argument must specify the mailbox logical name. The ACMODE 
argument has the same meaning as in the Create Mailbox service. The 
VAX/VMS System Services Reference Manual describes the Assign I/0 


Channel system service in detail. 








To delete a permanent mailbox, you must mark it for deletion using the 
Delete Mailbox (SDELMBX) system service. Actual deletion occurs, 
however, when all processes have deassigned the I/O channels 
connecting them to the mailbox or closed the file in a high-level 
language program. To deassign the I/O channel, use the Deassign I/0 
Channel (SDASSGN) system service. 


3.2.3 Example Using a Mailbox 


Figure 3-1 is a simple illustration of cooperating processes using a 
mailbox. 





PROGRAM MASTERPROC 
INTEGER*4 SYSSCREMBX,SYSSCREPRC ,STATUS ,CHAN 









C-- Create a mailbox and call it BOX' 


@ STATUS = SYSSCREMBX(,CHAN,,,,,'MAILBOX') 
IF (.NOT. STATUS) CALL LIBSSTOP(%VAL (STATUS) ) 


C-- Create a subprocess running program 'SUBPROC' and assign its input to be 
C-- the mailbox and its output to be our terminal 


@ STATUS = SYSSCREPRC(,'SUBPROC', 'MAILBOX', 'TTD6:',,77,%VAL(2) p44) 
IF (.NOT. STATUS) CALL LIBSSTOP ($VAL (STATUS) ) 


C-- Send the subprocess a message (in this case the number 12345) 
© opEN (UNIT=1,NAME='MAILBOX',STATUS='NEW') 


WRITE(1,*) 12345 
END 


PROGRAM SUBPROC 
C-- Read the message from the mailbox and, in this case, just display it 
@ AccEPT *,MESSAGE 

TYPE 10,MESSAGE 


FORMAT(' The message was: ',I15) 
END 








Figure 3-1 Using a Mailbox to Communicate 


Notes on Figure 3-1: 
One process creates a mailbox. 
The process creates a Subprocess. 


The creating process writes a message to the mailbox. 


So) 


The Subprocess reads the message. 
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3.3 ASYNCHRONOUS SYSTEM TRAP SERVICE ROUTINES 


An asynchronous system trap (AST) is a software-simulated interrupt 
used for event notification within a process. An AST service routine 
is a user-written routine that receives control when an AST is 
"delivered" after being queued to the process. The AST is delivered 
to the process (that is, interrupts the process execution flow) as 
soon as no higher-priority process is executable, unless specific 
conditions temporarily prevent it from being delivered (see Section 
3.3.2). When the AST service routine completes, the current image 
continues executing from the point at which it was interrupted. ASTS 
are thus a mechanism to allow asynchronous operations. 


3.3.1 System Services with AST Service Routine Arguments 


Several system services allow you to specify an AST service routine to 
be executed when the requested operation is completed. The call to 
the service initiates the request, and an AST is queued to the process 
when the request is completed. These services are as follows: 


@ Queue I/O Request ($QIO) 
e Update Section File on Disk (SUPDSEC) 
@e Get Job/Process Information (SGETJPI) 


The Set Timer (SSETIMR) system service allows you to specify (1) an 
absolute or delta time for an AST to be queued to the process, and (2) 
the address of an AST service routine. 


The Set Power Recovery AST (SSETPRA) system service specifies. the 
address of an AST service routine to receive control after a power 
recovery is detected. 


The Declare AST (S$DCLAST) system service allows a process to queue an 
AST for itself at the same or a less privileged access mode and to 
specify an AST service routine. This service is particularly useful 
for testing an AST service routine and for initiating actions that 
must be performed in an AST service routine. 


The VAX/VMS System Services Reference Manual contains a chapter on AST 


services, including a discussion on writing an AST service routine. 





3.3.2 Access Modes and AST Delivery 


ASTS are queued for a process by access mode. An AST for a more 
privileged access mode always takes precedence over one for a less 
privileged access mode; that is, an AST will interrupt any AST 
service routine executing at a less privileged mode. Normally, AST 
service routines that you specify execute at user access mode; 
however, the process can receive ASTs from more privileged access 
modes (for example, a kernel-mode AST at I/O completion). 


Figure 3-2 shows a program interrupted by a user-mode AST, and _ the 
user~-mode AST service routine interrupted by a kernel-mode AST. 
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Figure 3-2 Access Modes and AST Delivery 


An AST cannot be delivered to a process, however, while any of the 
following conditions are true: 


@ An AST service routine is currently executing at the same or a 
more privileged access mode. 


e The current image is executing at a more privileged access 
mode than the mode for which the AST is declared. 


e You have explicitly disabled AST delivery using the Set AST 
Enable (S$SETAST) system service. 


e The process is suspended (see Section 3.4). 


3.4 HIBERNATION AND SUSPENSION 


Hibernation and suspension are two synchronization mechanisms that 
allow a process to control when it or another process becomes active. 
Hibernation and suspension both temporarily halt the execution of a 
process; however, there are differences in how the mechanisms 
operate. Table 3-4 contrasts hibernation and suspension. 


COMMUNICATING AND SHARING BETWEEN PROCESSES 


Table 3-4 
Hibernation versus Suspension 














Hibernation Suspension 
1. Process can cause only 1. Process can suspend 
itself to hibernate itself or another 
process, depending on 


privilege 


2. Interruptible; ASTs can 
be delivered to the process 


2. Not interruptible; ASTs 
can be queued but not 


delivered 
3. Reversed by SWAKE system 3. Reversed by SRESUME 
service system service 
4. Process can wake itself or 4. Process cannot cause 
be awakened by another process itself to resume; 
another process must 


cause resumption 


5. Process can schedule wakeup at 5. Process cannot’ schedule 


absolute time or fixed time resumption 
interval (SSCHDWK service) 
6. Hibernate/wake complete 6. SSUSPEND service uses 


quickly and require 
little system overhead 


system dynamic memory; 
resumption takes longer 











The next two subsections provide coding examples illustrating two 
common uses of hibernate/wake: 


e Activating a process as needed 
e Activating a process at fixed intervals 


Note that in both examples the process to be awakened is identified by 
process identification number rather than by process name. Either 
method is acceptable; however, when a process is identified by 
process identification number, the system service executes slightly 
faster, because it does not have to search the process name table. 


3.4.1 Example 1: Wakeups as Needed 


PROCESS1 creates PROCESS2 as a Subprocess or detached process, but 
wants the created process’ to run only when certain events occur or 
certain conditions are true. Therefore, PROCESS1 sets bit 5 in the 
STSFLG argument to the Create Process system service call, causing 
PROCESS2 to hibernate immediately after it is created. PROCESS2 is 
activated only when PROCESS1 so requests, and PROCESS2 returns to 
hibernation immediately after it does whatever the specific 
application requires (for example, writing information to a mailbox 
used by both processes). 
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PROCESS 1 Wakes PROCESS2 whenever necessary 


PROCESS2_ ID: -BLKL 1 ;RECEIVE ID OF CREATED PROCESS 
PROCESS2 NAME: .ASCID /PROCESS2/ ;NAME OF CREATED PROCESS 


SCREPRC_S PIDADR=PROCESS2_ID,- ;CREATE PROCESS2 
PCRNAM=PROCESS2_NAME,-~ ;SPECIFY NAME 
STSFLG=#"B10000,- ;PROCESS2 STARTS IN HIBERNATION 

. ; (OTHER ARGUMENTS, AS NEEDED) 

BSBW ERROR 7;BRANCH TO ERROR-CHECKING ROUTINE 

SWAKE_S PIDADR=PROCESS2_ ID ;WAKE PROCESS2 

BSBW ERROR ;BRANCH TO ERROR-CHECKING ROUTINE 


SWAKE S PIDADR=PROCESS2 ID ;WAKE PROCESS2 


BSBW ERROR ;BRANCH TO ERROR-CHECKING ROUTINE 


PROCESS2 Awakens, performs functions, then goes back to sleep 


ENTRY START,O 7 IMAGE ENTRY POINT & MASK 
. ; (PERFORM FUNCTIONS) 
RET ;BACK TO HIBERNATION 


3.4.2 Example 2: Wakeups at Fixed Intervals 


PROCESSI1, a process with a priority in the timesharing range, creates 
PROCESS2 as a subprocess or detached process with a real-time base 
priority. PROCESS2 will run only at a fixed interval, in this case 
every hour, although its priority helps to ensure that when it does 
run it will run without interruption. 


PROCESS2 hibernates immediately after it is created. PROCESS1 used 
the Schedule Wakeup (SSCHDWK) system service to schedule a wakeup for 
PROCESS2 in one hour (DAYTIM argument) and every hour’ thereafter 
(REPTIM argument). When PROCESS2 is activated, it performs its tasks 
and returns to a state of hibernation. 
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PROCESS1 Process with timesharing priority 


PROCESS2_ ID: -BLKL A 7RECEIVE ID OF CREATED PROCESS 
PROCESS2 NAME: .ASCID /PROCESS2/ ;NAME OF CREATED PROCESS 
A1lHOUR: .ASCID /0 01:00:00.00/ ;ONE HOUR (DELTA TIME) IN ASCII 


B1HOUR: .BLKQ 1 ;QUADWORD TO HOLD BINARY TIME VALUE 
SCREPRC S PIDADR=PROCESS2 ID,...- ;CREATE PROCESS2 
~ ,PCRNAM=PROCESS2 NAME,- 
BASPRI=#17,... ;REAL-TIME PRIORITY 
BSBW ERROR ;BRANCH TO ERROR-CHECKING ROUTINE 
SBINTIM S TIMBUF=A1HOUR,- ;CONVERT TIME TO BINARY 
“~~ ‘TIMADR=B1HOUR 
BSBW ERROR ;BRANCH TO ERROR-CHECKING ROUTINE 


SSCHDWK S PIDADR=PROCESS2 ID,- ;SCHEDULE WAKEUP FOR PROCESS2 
“~~ DAYTIM=B1HOUR,—_ ; IN ONE HOUR, 
REPTIM=B1HOUR ; AND EVERY HOUR THEREAFTER 
BSBW ERROR ;BRANCH TO ERROR-CHECKING ROUTINE 


. ; (CONTINUE PROGRAM EXECUTION) 


PROCESS2 High priority real-time process 


»-ENTRY START,O 7 IMAGE ENTRY POINT & MASK 
SLEEP: SHIBER_S ;SLEEP TILL NEXT SCHEDULED WAKEUP 
BSBW ERROR ;BRANCH TO ERROR-CHECKING ROUTINE 
. ; (PERFORM HIGH-PRIORITY TASKS) 
BRW SLEEP ;BACK TO SLEEP (FOR ONE HOUR) 


A specific application of this example might involve a routine that 
needs to run periodically to gather and process status information. 
The routine might run for only a very short time, for example, a few 
seconds every hour. To prevent the routine from being interrupted, 
you can assign its process a real-time base priority and use any of 
the other methods discussed in Chapter 2. 


3.5 GLOBAL SECTIONS 


A global section is an area of memory containing data or code that can 
be shared by cooperating processes, One process "creates" the 
section; subsequent processes establish their right to use the 
section by "mapping" to it. The data or code in the section can be 
from a disk file (disk file section) or in physical memory or I/0 
space (page frame section). This section discusses disk file 
sections. Physical page frame sections are treated in Chapter 4 in 
the discussion of connecting to an interrupt vector. 
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In many real-time applications, such as data acquisition or industrial 
process-control, response time is so critical that control variables 
and data readings must remain in memory. Frequently, many different 
processes must use this data simultaneously. Global sections provide 
a convenient mechanism for fast access to the data and for the rapid 
passing of data from one process to another. 


Gliobal sections can be temporary or permanent. Temporary sections are 
deleted when no processes are mapped to them, but permanent sections 
must first be explicitly marked for deletion with the Delete Global 
Section ($DGBLSC) system service. Most global sections that you 
create from within your programs should be temporary, so that’ the 
system resources associated with the section can be freed as soon as 
they are no longer needed. Temporary global sections in real-time 
applications usually contain data rather than code. Permanent global 
sections, on the other hand, usually contain routines common to 


several programs. In fact, most of the permanent global sections in 
the system are shareable images installed by the system manager as 
known images. (Shareable images are discussed in Section 3.6. The 


INSTALL utility is explained in the VAX/VMS System Manager's Guide.) 


VAX-11 Record Management Services (VAX-11 RMS), with its file-sharing 
capabilities, provides an alternative to global sections in some cases 
as a mechanism for sharing disk file data. Each method has its 
advantages; however, global sections provide the faster access that 
many real-time applications require. Table 3-5 shows the trade-offs 
involved in choosing between a global section and VAX-11 RMS for 
sharing disk file data. 


Table 3-5 
Global Sections versus VAX-11 RMS 







Global Sections VAX-11 RMS 





















1. Faster access to data 1. Access to data slowed by 


file-system overhead 


2. More programming effort 
required; user must define 
and keep track of service 
arguments and other data 


2. Programming simplified by 
VAX-11 RMS or high-level 
language macros; most 
internal operations and 
data structures transparent 
to the user 


3. Greater burden on the 
user to protect data 
and synchronize access 


3. Automatic file protection 
and synchronization of 
access, based on parameters 
supplied by user 


4, Especially suited for 
small files 


4. Especially suited for large 
files 





Chapter 5 discusses global sections in shared (multiport) memory. 
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3.5.1 Creating and Mapping a Global Section 


The Create and Map Section (SCRMPSC) system service creates a section 
or maps to an existing section. The VAX/VMS System Services Reference 
Manual has a detailed description of this service and a_ lengthy 
discussion of sections in general. The present manual gives only the 
general format for calling the service and discusses a few arguments 
especially significant to real-time users. 


The Create and Map Section system service has the following general 
formats: 


MACRO Format 


SCRMPSC [inadr], [retadr], [acmode], [flags], [gsdnam], [ident] 
,(relpag], [chan], [pagent], [vbn], [prot], [pfc] 


High~Level Language Format 


SYSSCRMPSC ([inadr], [retadr], [acmode], [flags], [gsdnam], [ident] 
,(relpag],{chan], [pagent], {vbn],[fprot], [pfcl) 


The FLAGS argument specifies a mask defining the section type and 
characteristics. This mask is the logical OR of the flag bits you 
want to set. (The SSECDEF macro defines the symbolic names for’ the 
flag bits in the mask.) To specify a global section, you must set the 
SECSM_GBL flag bit. You can set additional flag bits as needed. The 
flag bit meanings and the default values they override are listed 
below. 


Flag Meaning Default Attribute 
SECSM_GBL Global section Private section 
SECSM_CRF Pages are copy~on-reference Pages are shared 
SECSM_DZRO Pages are demand-zero pages Pages are not zeroed 

when copied 

SECSM_EXPREG Map into first available Map into range speci- 

space fied by INADR argument 
SECSM_WRT Read/write section Read-only section 
SECSM_ PERM Permanent Temporary 
SECSM_PFNMAP Physical page frame section Disk file section 
SECSM_SYSGBL System global section Group global section 
The PROT argument specifies a numeric value representing the 


protection mask to be applied to the section. To deny read or write 
access to the section to one or more types of user, you must specify 
the appropriate protection mask. If you do not specify this arqument, 
all users have read and write access to the section. 
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The protection mask has four 4-bit fields: 


15 11 7 3 0 
| WORLD | GROUP | OWNER | sere 


Bits are read from right to left in each field and indicate, when they 
are set, that read, write, execute, and delete access (in that order) 
are denied for that particular category of user. However, the 
following considerations apply to any protection mask you specify: 





e Only read and write access are meaningful for section 
protection. Denying execute or delete access has no effect. 


e For group global sections the "World" field has no effect, 
because only members of the creator's group are permitted to 
map to the section. The "World" field does apply, however, to 
system global sections, 


For example, to allow the owner of a group global section to read and 
write to the section but allow other members of the group only to read 
the section (that is, to deny them write access), specify a protection 
mask of 0200 (hexadecimal). 


3.5.2 Other Section-Related System Services 
The following system services are often used with global sections: 


e Map Global Section (SMGBLSC). Maps an existing global 
section. 


e Update Section File on Disk (SUPDSEC). Writes the modified 
pages of a section back to the disk file. This system service 
is especially useful for periodically updating a data base 
that is being modified by multiple processes. 


e Delete Virtual Address Space (SDELTVA). "Unmaps" a global 
section by deleting the process's virtual addresses into which 
the section was mapped. 


e Delete Global Section (SDGBLSC). Marks a global section for 
deletion. Actual deletion occurs when no processes are mapped 
to the section. 


3.6 SHAREABLE IMAGES 


Shareable images can be used to share frequently used code or data 
among multiple processes. A shareable image might contain routines 
that are common to several programs. If a sShareable image is 
installed in the system as a permanent global section (as is normally 
the case), other programs can share its contents by linking with it. 
The benefits of using shareable images include reductions in disk 
storage space, physical memory use, and system paging activity. The 
VAX-11 Linker Reference Manual explains the benefits and uses of 
Shareable images in detail. 
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In the airline reservation example in Chapter 7, the reservation data 
base is a shareable image. 


To use a shareable image effectively, you must create the shareable 
image and then permit other programs to use it. 


To create a shareable image, you must perform the following steps: 


1. Code the program containing the routine or data to be shared. 
Design this program to meet the needs of all other programs 
that will be using it (that is, all programs that will be 
linked to the shareable image). Follow the programming 
conventions discussed in the chapter on shareable images in 





2. Assemble or compile the program containing the shareable code 
or data. For example: 


$ MACRO SHCODE 


This command generates the object module SHCODE.OBJ in your 
default directory (assume that this is DBl: [SMITH] for this 
and the remaining steps). 


3. Link the object module to produce a shareable image, using 
the /SHAREABLE command qualifier. For example: 


$ LINK/SHAREABLE SHCODE 


This command generates the shareable image SHCODE.EXE in your 
’ default directory. 


To permit other programs to use the shareable image, you must perform 
the following steps: 


l. Create a linker options file. Identify the shareable image 
to be used with the /SHAREABLFE file qualifier. For example, 
create a file named A.OPT containing the following line: 


DB1: [SMITH] SHCODE/SHAREABLE 


2. Link each program that will use the shareable image, 
identifying the linker options file with the /OPTIONS file 
qualifier. For example: 


SLINK PROGRAM1 ,A/OPTIONS 


This command generates an executable image named PROGRAM1 
that is linked with the shareable image SHCODE. 


To permit multiple processes to use the same copy of the shareable 
image, install it as a known image, using the INSTALL utility. (The 
VAX/VMS System Manager's Guide explains the INSTALL utility.) It is 
recommended that you copy the shareable image file to the directory 
identified by the logical name SYSSSHARE (which by default is [SYSLIB] 
on the system disk), and then run INSTALL: 





$ RUN SYSSSYSTEM: INSTALL 
INSTALL>SYSSSHARE : SHCODE/OPEN/SHARED 


The example above designates the shareable image as a permanent global 
section, that is, a permanently open section potentially available to 
all users of the system. 
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Note that the VAX/VMS image activator assumes that shareable images 
linked with the executable image being run are located in SYSSSHARE. 
To have the image activator look for a shareable image in a different 
location, define the shareable image file name as a logical name with 


the file specification as the equivalence name before running the 
executable image. For example: 


$ DEFINE SHCODE DB1: [SMITH]SHCODE 


CHAPTER 4 


PERFORMING I/0 OPERATIONS 


A real-time VAX/VMS process can use the VAX/VMS I/O system to perform 
I/O operations, or it can bypass most of the I/0 system by 
manipulating device registers and responding to device interrupts 
directly. Before you can optimize I/0 operations for a real-time 
application, however, you must understand the components that form the 
VAX/VMS I/O system and how they interact. 


4.1 OVERVIEW OF THE VAX/VMS I/O SYSTEM 
The VAX/VMS I/O system has the following major components: 
e The Queue I/O Request system service 
e Device drivers 
@ Ancillary control processes (ACPs) 
e The I/0 posting routine 


The following subsections describe the main functions of these 
components. 


4.1.1 Queue I/O Request System Service 


Every I/O request issued by a process under VAX/VMS results directly 
or indirectly in the invocation of the Queue I/O Request system 
service. For example, both a FORTRAN READ statement and a VAX-11 RMS 
SGET request from a VAX-11 MACRO program cause the Queue I/O Request 
system service to be called. 


You can call the Queue I/O Request system service specifying one of 
three types of function code: physical, logical, or virtual. The 
service validates the device-independent portions of the I/O request. 
The device driver or ancillary control process (ACP) performs any 
necessary validation of the device-dependent portions of the I/0 
request. 


The VAX/VMS I/O User's Guide lists the valid function codes for each 
device driver or ACP and provides guidelines for choosing among 
function codes when alternatives are available. 


PERFORMING I/0 OPERATIONS 


4.1.2 Ancillary Control Processes 
An ancillary control process (ACP) is a VAX/VMS process that performs 
I/O-related functions associated with file structures and protocol, 
rather than functions related to the actual transfer of data. VAX/VMS 
supplies at least five ACPs: 

@ Two or more ACPs for Files-ll structured disk devices 

e One ACP for ANSI magnetic tapes 

@ NETACP for network functions 

@ REMACP for remote terminal I/O functions 
The use of ACPs is normally transparent to your programs. VAX-11 RMS 
issues the necessary Queue I/0 Request system services for virtual 
functions on your behalf. You can, however, issue Queue I/O Request 
system service calls directly for Files~-1l disk and magnetic tape ACPs 
to request such functions as the following: 

@ File creation 

@ File access 

e Reading and writing of virtual blocks 


@ File deletion 


The VAX/VMS I/O User's Guide describes the use of ACPs by user 
processes, 








When a user process or VAX-11 RMS issues a Queue I/0 Request’ system 
service for an ACP function, the Queue I/O Request system service 
passes the request to the appropriate ACP. The ACP processes” the 
request (if necessary), converts the function from virtual to logical 
(if necessary), and queues the request to the appropriate device 
driver. The driver performs the transfer, as described in Section 
4.1.3. 


4.1.3 Device Drivers 
Device drivers are responsible for taking the information that’ the 
Queue I/O Request system service provides about an I/O request and 
performing the I/O operation. To accomplish these tasks, a driver 
contains the following main routines: 

e Device activation routine 

e Interrupt service routine 

e I/0 completion routine 
Drivers also contain other routines to handle request validation and 


such contingencies as power failure and device timeout, as described 
in the VAX/VMS Guide to Writing a Device Driver. 
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The device activation routine obtains the device controller resources 
needed to perform the transfer (for example, the controller data 
channel), sets up device registers in I/0 space, and initiates the 
transfer. Once the transfer is initiated, the device activation 
routine issues a wait request that temporarily suspends the device 
driver. 


When the transfer is complete, the device requests an interrupt and 
the system activates the driver's interrupt service routine to handle 
the interrupt. (Section 4.6 discusses interrupt handling.) In 
addition to handling the interrupt, the interrupt service routine may 
program the device for another transfer or may activate the I/0 
completion routine in the driver to perform device-dependent I/0 
completion. The driver's I/O completion routine, in turn, passes 
control to the VAX/VMS I/0 posting routine. 


4.1.4 1/0 Posting Routine 


Once the device driver has finished the device-dependent portions of 
the I/O request, it calls the I/O posting routine. I/0 posting 
consists of completing the device-independent portions of the I/0 
request, setting a designated event flag (flag 0 by default), and 
queuing a kernel mode AST for the process that initiated the I/0 
request. 


The next time the system schedules this process for execution, the 
kernel mode AST routine executes. This routine completes the I/0 
request by performing the following functions: 


e If requested, writes the status of the I/O request into a 
user-specified I/O status block. 


e If requested, queues an AST at the access mode of the Queue 
I/O request for the process to execute a user-specified 
routine. 


e For read requests that were buffered in system space, copies 
the data from system space into the user's buffer. Device 
drivers determine whether the data is read directly into the 
user buffer (direct I/0) or buffered first in system space 
(buffered I/O). 


The driver's I/O posting routine has a lower priority than the 
driver's start I/O routine. Therefore, if a new I/O request is queued 
for the device before the existing I/O request is completed, the new 


I/O is started. This method of operation keeps the device as busy as 
possible. 


4,2 USER INTERFACE TO THE I/O SYSTEM 


The design of the VAX/VMS I/O system allows user-written programs’ to 
interface with the system at a number of levels: 


@ VAX-11 Common Run-Time Procedure Library routines 
e VAX-11 Record Management Services (VAX-1l RMS) 
e Queue I/O Request system service for a device or ACP function 


e Connecting to a device interrupt vector 
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In addition, users can write device drivers to support devices not 
supported by VAX/VMS and incorporate those devices into the system. 


Programs written in VAX-1l MACRO can interface with the I/O system by 
using VAX-11 RMS, by using the Queue I/0 Request syStem service, or by 
mapping to I/O space and connecting to a device interrupt vector. 
Programs written ina high-level language can interface with the I/O 
system uSing the same methods as a VAX-11 MACRO program, or they can 
issue the I/O statements specific to that language. In the latter 
case, the program interfaces with the I/O system by means of the 
VAX-11 Common Run-Time Procedure Library. 


The following steps occur when a high-level language program, in this 
case VAX-11 FORTRAN, issues a read request under VAX/VMS: 


@ When the program executes, the read statement results in a 
call to the Run-Time Library read procedure to initiate the 
read operation. To initiate the read, the procedure issues a 
VAX-11 RMS SGET request. 


@ VAX-11 RMS gains control and, in turn, issues the appropriate 
Queue I/O Request system service. 


e The Queue I/O Request system service processes the request (as 
described in Section 4.1.1) and queues it to the driver or 
ACP. 


e Once the driver activates the device and completes the I/0 
operation, it calls the VAX/VMS I/O posting routine. 


e The VAX/VMS I/O posting routine then performs 
device-independent I/0 completion, returns status to the user 
program, and, if requested, queues an AST or setS an event 


flag. 
A user program can interface with the I/O system at one of several 
levels, depending on its requirements. At each level, the user 
program makes trade offs between ease of use and execution speed. As 


a general rule, the closer to the VAX/VMS executive that a user 
program interfaces, the less overhead is involved in the I/O 
operation. This manual focuses on the following lower levels of 
interface: the Queue I/O Request system service, the Create and Map 
Section system service, and the connect-to-interrupt capability. 


4,2.1  VAX-11 RMS Features of Interest to Real-Time Users 


VAX-11 Record Management Services has several features that may permit 
certain applications to take advantage of VAX-11 RMS and still meet 
their throughput and response requirements. Listed below are 
descriptions of these features, with the VAX-11 RMS mechanism 
associated with each feature, Complete descriptions of the features 
and mechanisms are given in the VAX-11 Record Management Services 
Reference Manual. ~ 
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Mechanism Feature 
SFAB ALQ=quantity Preallocation of enough blocks to hold the 
entire file, Avoids time-consuming file 
extensions and ACP window’ turns; prevents 


discontiguous file extensions. 


SFAB FAC=BIO Block I/O (for S$PUT operations). Faster 1/0 
because no RMS buffer is used. 

SFAB FOP=CTG Contiguous files. Faster access, especially for 
random access and/or files with many segments. 

SRAB MBF=buffers Multibuffering. Improves throughput. 

SRAB ROP=RAH Read-ahead and write-behind. Improve throughput 

SRAB ROP=WBH (done by default by certain high-level language 


compilers). 


SRAB MBC=blocks Multiblock I/O. Reduces number of disk accesses 
for record operations, 


4.3 USING THE QUEUE I/O REQUEST SYSTEM SERVICE 


The Queue I/O Request ($QIO) system service gives programmers in any 
supported language a low-level, flexible interface with the VAX/VMS 
I/O system. You must first assign an I/O channel to the device using 
the Assign I/O Channel (SASSIGN) system service. Your call to the 
Queue I/O Request system service must specify this channel and a 
function code identifying the operation to be performed. The optional 
arguments to the Queue I/O Request service allow you to do_ the 
following: 


e Perform asynchronous ($QIO form) or synchronous (S$QIOW form) 
I/O 


® Set an event flag at I/0 completion (EFN argument) 
e Receive the final completion status (IOSB argument) 


e Specify an AST service routine (ASTADR argument) to be 
executed when the I/O completes and pass a parameter (ASTPRM 
argument) to that routine 


@ Specify function-specific or device-specific parameters (Pl, 
P2, etc.) 


There are two forms of this service: Queue I/O Request (SQIO) and 
Queue I/O Request and Wait for Event Flag (SQIOW). The SQIO form 
returns control to the program immediately after queuing the I/0 
request and without waiting for the I/O to be completed; this form 
allows your program to perform asynchronous I/0. The SQIOW form waits 
until the 1/0 is completed before returning control to your program, 
(The SINPUT and SOUTPUT macros are special forms of SQIOW.) 
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The Queue I/O Request system service has the following general 
formats: 


MACRO Format 


SQIO[W] {efn],chan,func, [iosb], {astadr],fastprm], 
[pl),([p21,[(p3],[p4],fp5], fps) 


High-Level Language Format 


SYSSQIO[W] ({efn],chan,func, [iosb], fastadr],[astprm], 
(pl],[p2],{p3],[p4],[p5], [p6}) 


The VAX/VMS System Services Reference Manual has additional general 


information on this system service and some examples of its use. The 
VAX/VMS I/O User's Guide has specific information and examples of this 


system service for each of the device drivers it discusses. 








4.4 INTERRUPT-GENERATED I/0 


A process with suitable privileges can connect to a device interrupt 
vector and/or map the processor's I/0 space into process virtual 
address space. Connecting to a device interrupt vector allows your 
Process to respond to interrupts from the device with minimal 
overhead. Mapping processor I/O space allows your process to access 
device registers from the main program or from an AST service routine. 


A process normally uses these features for devices that do not have 
VAX/VMS drivers. These devices must not be direct memory access (DMA) 
devices, and they must be attached to the UNIBUS. Examples of such 
devices are the ADI1-K the DR11-B, and the Kwll-P. 


You can use the Queue I/0 Request (SQIO) system service with an 
appropriate function code to connect to a device interrupt vector and 
to specify a user-supplied routine, called an interrupt service 
routine (ISR), that VAX/VMS executes when the designated device 
interrupts. Connecting to a device interrupt vector allows you to do 
the following: 


e Respond to an interrupt within a very short time 


@ Preempt other system processing to handle a real-time event, 
for example, a clock interrupt 


e Buffer data from a device in real time and return the data _ to 
the process at a later time 


® Set an event flag or queue an AST to your process after 
receiving the interrupt 


The effect of user~written interrupt service routines is to allow you 
to perform some of the functions normally done by a device driver, but 
without requiring that you write a full device driver and without 
requiring that the routine be loaded into the VAX/VMS operating system 
(device drivers are part of VAX/VMS). 


PERFORMING 1/0 OPERATIONS 


If you must access device registers from user mode (that is, from the 
main program or a user-mode AST service routine), you must use the 
Create and Map Section ($CRMPSC) system service to map I/O space, 
specifying page frame number (PFN) mapping. The service creates a 
global or private section that maps the specified I/O pages into your 
process's virtual address space. The process can then gain access to 
I/O space using virtual addresses. 


You do not need to map I/O space to access device registers from any 
of the following routines specified in the SQIO call connecting to an 
interrupt vector: device initialization routine, start I/O routine, 
interrupt service routine, and cancel I/O routine. These routines 
execute in system space and thus can access UNIBUS I/O space, which is 
mapped as part of system space. 


The sections that follow explain how to map the VAX-11 processor's I/0 
Space and how to connect to a device interrupt vector. 


4.5 MAPPING I/O SPACE 


On a VAX-11/780 processor, I/0 space is assigned physical address 
locations of 20000000 (hexadecimal) and higher. I/0 space contains 
device registers that a driver or user process can read and write to 
control a device. Each device controller has an associated 
control/status register in I/O space, Device registers for each 
device are located at an offset from the device's control/status 
register (CSR). 


The SIO780DEF macro defines the following symbols describing the 
layout of VAX-11/780 I/0 space: 


Symbol Meaning Hexadecimal 
value 

IO0780SAL_IOBASE Start of I/0 space 20000000 

IO0780SAL_UBOSP Start of address space for 20100000 


first UNIBUS 
These symbols are contained in SYSSLIBRARY:LIB.MLB. 


The number of registers and their locations vary for different 
devices. The PDP-11 Peripherals Handbook provides’ the necessary 
information for devices supplied by DIGITAL. The VAX-11/780 Hardware 
Handbook contains information about the layout of I/O space. 








On a VAX-11 processor, the address of a physical memory location has 
the format illustrated in Figure 4-1. 


| ' 
| 29 « 918 0 
! \ 


page frame number byte 





Figure 4-1 Physical Address 


The page frame number (bits 9 through 29) specifies the number of a 
physical page in memory. Bit 29 is clear to indicate a physical 
memory address and set to indicate an address in I/O space. Bits 0 
through 8 specify the byte address within the page. 
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For a process to gain access to I/O space or to any page of physical 
memory, it must map that page into its virtual address space. When 
your VAX/VMS process mapS a page by specifying its page frame number, 
it completely bypasses VAX/VMS memory management and creates its own 
window to the page. As a result, the protection functions that 
VAX/VMS normally performs are not performed for mapping by page frame 
number: 


@ No checks are performed to ensure that no other VAX/VMS 
processes are mapped to the page and modifying it. 


e No reference count is maintained. A process can delete a 
global section mapped by page frame numbers when other 
processes are still using it; this is not the case when 


VAX/VMS performs the mapping. 


Modifying pages mapped by page frame numbers can have unpredictable 
results and can adversely affect system operation, especially if the 
operating system is also using these pages. Because of the 
unprotected nature of mapping by page frame numbers, you must have the 
PFNMAP user privilege to use this capability. 


4.5.1 Page Frame Number (PFN) Mapping 


When used for mapping by page frame number, the Create and Map Section 
system service designates the specified page(s) as a global or private 
section and maps the section into the requesting process's virtual 
address space. The pages can he located anywhere in the VAX-11 
processor's local memory, or in MA780 memory (if a multiport memory 
unit is connected to the system), or in I/O space. 


The format and conventions for mapping by page frame number (that is, 
mapping a physical page frame section) are similar to those for 
mapping a disk file section. The Create and Map Section system 
service has the following general formats: 


MACRO Format 


SCRMPSC {inadr] ,{retadr] ,[acmode] ,[flags] ,[fqsdnam] , [ident] 
,(relpag] ,[chan] ,[pagent] ,[vbn] ,[prot] ,[pfc] 


High~Level Language Format 


SYSSCRMPSC([inadr] ,{retadr] ,[acmode] ,[flags] ,[gsdnam] , [ident] 
,{relpag] ,{chan] ,[pagent] ,[vbn] ,[prot] ,[pfc]) 


The RELPAG, CHAN, and PFC arguments are not applicable in mapping by 
page frame number. The INADR, RETADR, ACMODE, GSDNAM, IDENT, and PROT 
arguments have the same functions regardless of whether you. specify 
page frame number mapping; these arguments are described in the 





The following arguments are affected by PFN mapping: 
flags 
Mask defining the section type and characteristics. This mask is 


the logical OR of the flag bits you want to set. The SSECDEF 
macro defines symbolic names for the flag bits in the mask. 


pagen 


vbn 


Notes 
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The SECSM PFNMAP flag bit must be set to indicate mapping by page 
frame number. The SECSM PFNMAP flag setting identifies the memory 
for the section as starting at the page frame number specified in 
the VBN argument and extending for the number of pages specified 
in the PAGCNT argument. 


If appropriate, the following flags can also be Set: 


Flag Meaning Default 

SEC$_GBL Global section Private section 
SECSM_WRT Read/write section Read-only section 
SECSM PERM Permanent section Temporary section 


SECSM SYSGBL System global section Group global section 
SECSM_EXPREG Expand the process's Map into range 
virtual address space specified by 
as needed to contain INADR argument 
the section. 


Neither the SEC$M_CRF (copy-on-reference) nor the SECSM_DZRO 
(demand-zero) bit can be set when mapping by page frame number. 


The VAX/VMS System Services Reference Manual provides additional 
information about the use of the flag settings. 








t 


Number of pages in the section; the value of this argument must 
not be zero. 


Page frame number of the first page to be mapped (aS opposed _ to 
this argument's normal usage identifying the starting virtual 
block number within a disk file). When you are mapping more’ than 
one page with a single Create and Map Section system service 
request, the pages are physically contiguous starting with the 
specified page. 


1. An error in mapping UNIBUS I/O space or ae reference to a 
nonexistent UNIBUS address causes a UNIBUS adaptor error. 
However, this error does not cause a system failure. Rather, 
an entry is made in the system error log file and the user 
program continues executing (probably with erroneous results). 
The process is not notified of the UNIBUS adapter error. 


2. If a power failure occurs on the UNIBUS, the system continues 
to run. However, if a user process accesses UNIBUS I/O space 
from user mode during a UNIBUS power failure, the process 
receives a machine check exception. To handle this condition, 
the process must have a condition handler to deal with machine 
check exceptions. The VAX/VMS System Services Reference 


Manual discusses condition handlers in detail. 





3. During recovery from a UNIBUS adaptor power failure, the 
processor spends a considerable amount of time (perhaps 10 to 
60 milliseconds) at interrupt priority level (IPL) 31. This 
action blocks user processes from executing during the 
recovery. 
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4.5.2 Programming Conventions for Addressing Device Registers 


Once you have mapped to I/O space, you can read data from a device data 
buffer register or enable interrupts by setting a bit in a 
control/status register, because the device registers are now 
addressable as part of your process's virtual memory. The UNIBUS 
adapter performs the actual mapping of VAX-11 virtual addresses’ to 
18-bit UNIBUS addresses that correspond to device registers. 


Because UNIBUS devices are one word (16 bits) long, all instructions 
referring to these registers must be word-context instructions (for 
example, BISW, MOVW, and ADDW3), unless the register is byte 
addressable. Instructions referring to byte-addressable registers 
should be byte-context instructions, such as BISB and MOVB. Unaligned 
references and references using a length attribute other than the 
length of the register may produce unpredictable results; for 
example, a byte reference to a word-addressable register does not 
necessarily respond by supplying or modifying the byte addressed. A 
longword reference to a UNIBUS location causes a machine check. 


Instructions that use a UNIBUS device register as a source operand 
must not be interruptible instructions. In some cases when a device 
register is being copied, interrupting and restarting an instruction 
may cause a character to be lost. To guarantee a noninterruptible 
sequence, use only the instructions listed in Appendix C of the 
VAX-11/780 Hardware Handbook, and do not use autoincrement deferred 
addressing mode or any of the displacement deferred addressing modes. 
You should always store the address of a device control register ina 
general register and then gain access to the device indirectly through 
the general register. 








The example below defines symbolic word offsets for each device 
register and gains access to them using displacement mode addressing 
from R4,. 


Device register offsets 


we Ne Ne 


LP_CSR = 0 ; CSR offset 

LP DBR = 2 ; Buffer address offset 
MOVL CSR_VA,R4 ; Get CSR address 
TSTW LP_CSR(R4) ; Is printer online? 


The following restrictions also apply to instructions addressing 
device registers: 


@ Operand types of floating, double, field, queue, or quadword 
are not allowed, nor can the position, size, length, or base 
of an operand be from I/O space. For example, a field 
instruction cannot be used to test a bit in a device register. 


e You cannot have more than one modify or write destination, and 
this modify or write destination must be the last operand. 


e Instructions referring to I/0 space must not cause an 
exception after the first I/0 space reference. This 
restriction includes deferred references to I/O space. 
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4.6 CONNECTING TO AN INTERRUPT VECTOR 


On a VAX-11 processor, peripheral devices have interrupt vectors 
associated with them. When a device interrupt occurs, the action 
taken by the processor depends on the interrupt priority level (IPL) 
associated with the device, 


Connecting to an interrupt vector differs from the standard method of 
programming a peripheral device. Programming a peripheral device is 
normally a 3-step loop: 


1. The device driver starts the device and enables interrupts 
from the device. 


2. The device generates an interrupt. 


3. The device driver fields the interrupt, collects status and 
data, and clears the interrupt condition. 


Under the VAX/VMS operating system, a user program normally requests 
I/O by means of a Queve I/O Request ($QI0) system service call. A 
device driver, executing as part of the operating system, controls and 
responds to the device. The driver returns Status and data to the 
requesting user process. 


However, real-time application programmers can connect to an interrupt 
vector to control and respond to a device without writing a full VMS 
device driver, and without issuing S$QIO calls for each device 
interaction. Instead, you issue a connect-to-interrupt SQIO call that 
specifies code to be executed to control the device, and a data area 
that the program and the device control code can_ share, You 
subsequently control and respond to the device without additional SQIO 
calls. 


The timings involved in different system activities associated with 
connecting to an interrupt vector are as follows: 


e The time between when the device generates an interrupt = and 
when the process's interrupt service routine receives control 
depends upon the IPL of the processor at the time of the 
interrupt. If the processor is executing at an IPL below that 
of the device (as is the usual case), the interrupt service 
routine gains control within a few microseconds. However, if 
the processor is executing at an IPL above that of the device, 
the interrupt service routine does not gain control until the 
executing code lowers the IPL below the device IPL. (Section 
4.6.1 discusses IPLs.) 


e The time from the user interrupt service routine's exit to the 
execution of the AST routine specified in the $OIO call 
depends on the priority of the process and whether a context 
switch is required. 


4.6.1 Interrupt Priority Levels 


VAX-11 processors define 32 hardware interrupt priority levels. These 
interrupt priority levels establish the order in which peripheral 
devices, error condition reporting, and various components of VAX/VMS 
gain access to the processor; that is, interrupt priority levels are 
a synchronization mechanism. (Interrupt priority is not related to 
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process priority, which is discussed in Section 1.6.) VAX/VMS and 
VAX-1l1 processors assign the interrupt priority levels (IPLs) as 
follows: 


@® User mode programs run at IPL 0; this is the lowest IPL. 


e@e VAX/VMS routines) and device driver processes request 
interrupts at IPLs 1 through 15. (Device drivers execute as 
fork processes under VAX/VMS, as described in the VAX/VMS 
Guide to Writing a Device Driver.) 


e Peripheral devices generate interrupts at IPLs 16 through 19. 
UNIBUS peripherals generate interrupts of IPLs 20 through 23 
(corresponding to UNIBUS BR levels 4 through 7). 


® Processor error conditions and the system clock generate 
interrupts at IPLs 20 through 31. 


Because of the way in which priority levels are assigned, device 
interrupts almost always receive immediate service from the processor 
and VAX/VMS. 


A VAX-11 processor always executes the code associated with the 
highest IPL for which an interrupt has been requested. For example, 
if the processor is executing a driver process and a device requests 
an interrupt, the processor stops executing the driver, saves the 
driver's context for subsequent reactivation, and activates’ the 
interrupt service routine for the interrupting device. When that 
interrupt service routine terminates, VAX/VMS activates the code 
associated with the next lower IPL for which an interrupt has been 
requested. The routine activated can be either of the following: 


e® A routine that had already started execution but was 
interrupted by a higher level interrupt 


e A routine for which an interrupt has been pending while the 
processor executed at a higher IPL but which had not been 
executed previously 


4.6.2 Performing the Connect-To-Interrupt 


Connecting to a device interrupt vector allows your program to receive 
notification of an interrupt from a designated device by any 
combination of the following means: 


e By execution of a user-Supplied interrupt service routine 
e By the setting of an event flag 


e By execution of an AST routine that is to gain control in 
process context 


In addition, you can specify a cancel routine that is to be executed 
when the process disconnects from the interrupt vector or is deleted. 


Before your program can run, the system manager must have done the 
following at system generation time: 


e Specify the REALTIME SPTS parameter to the SYSGEN utility, 
reserving system page table entries for use by real-time 
processes. These system page table entries are used to map 
process~specified buffers in system space (see the Pl argument 
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description in Section 4.6.5). The REALTIME SPTS parameter 
value must be greater than or equal to the number of pages in 
buffers specified by processes connected to interrupt vectors. 


e Configure the real-time device by issuing a CONNECT command to 
the SYSGEN utility. This command names’ the device; its 
vector, register, and adapter addresses; and ae skeletal 
driver (CONINTERR) for the device. 


The CONNECT command to the SYSGEN utility is explained in the VAX/VMS 
System Manager's Guide. 





At run time the process calls the SASSIGN system service to associate 
a channel with the device, The process can also map the page in 
UNIBUS I/O space containing the device registers (see Section 4.5). 
To connect to the device interrupt vector, the process issues a $QIO 
call specifying the IOS CONINTREAD or I0S$ CONINTWRITE function code 
and as many of the following as are appropriate: 


e An interrupt service routine to be executed when the device 
generates an interrupt 


e A buffer containing code to be executed in system context 
andfor data (This buffer must be contiguous in the process's 
address space.) 


e An AST service routine to execute and/or an event flag to be 
set after the interrupt service routine (if any) completes (If 
an AST service routine is specified, an AST parameter may also 
be specified.) 


e A device initialization routine 
e A start I/O routine 
e A cancel I/O routine 


A nonprivileged process (that is, lacking the CMKRNL privilege) can 
also connect to an interrupt vector, but it can only specify an AST 
service routine to be executed or an event flag to be set (or _ both) 
when an interrupt is generated. Section 4.6.5 explains the SQIO 
format for connecting to an interrupt vector, 


4.6.3 The Connect-To-Interrupt Driver 


The VAX/VMS connect-to-interrupt driver (CONINTERR) provides a_ driver 
interface to the system on behalf of the process. CONINTERR connects 
the process to the device by executing the following steps: 


1. Validates the $QIO system service parameters, such as_ the 
process's access to the specified buffer, and the number of 
the optional event flag. 


2. Locks the physical pages of the buffer into physical memory, 
and maps the pages using system page table entries allocated 
by the REALTIME SPTS parameter to the SYSGEN utility. 


3. Constructs argument lists and calling interfaces to the 
process-specified routines by storing values in the device's 
unit control block (UCB). 
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4. Allocates the specified number of AST control blocks to. the 
process, and inserts each block in a queue in the device's 
UCB. 


5. Transfers control to VAX/VMS to queue the connect to 
interrupt I/O packet to CONINTERR start I/O routine. 


When the CONINTERR start I/O routine gains control, it passes control, 
by means of a user-specified JSB or CALLS interface, to the 
process~specified start-device routine. This routine usually 
initializes the device and may also start activity on the device. 


When the device generates an interrupt, the interrupt service routine 
in CONINTERR gains control. This routine transfers control to the 
process-supplied interrupt service routine. 


4.6.4 The Interrupt and AST Service Routines 


The interrupt service routine that you specify, like those supplied by 
VAX/VMS, has the following characteristics: 


e It is mapped in system space, 
e It executes on the interrupt stack. 


e It executes at the IPL of the device that requested the 
interrupt. 


Because of these characteristics, the interrupt service routine 
executes as part of the VAX/VMS operating system rather than in the 
context of your user process. As part of the operating system, the 
interrupt service routine has access to system data bases not 
available to user processes. However, because an interrupt service 
routine has these capabilities and executes at a raised IPL, you must 
code it carefully to avoid disrupting the system. Section 4.6.9 
discusses conventions for process-specified interrupt service routine. 


The interrupt service routine that you specify usually performs one or 
more of the following steps: 


1. Copies data from a device register 
2. Writes to a device register to clear the interrupt condition 


3. Restarts the device, or returns an offset, a byte count, or 
actual data as an AST parameter 


4. Returns an interrupt status to the VAX/VMS 
connect-to-interrupt driver (CONINTERR) 


Depending on the interrupt status, the CONINTERR interrupt service 
routine queues a fork process to run at a lower IPL. Then the 
interrupt service routine exits from the interrupt with an _ REI 
instruction. When the CONINTERR fork process gains control, it queues 
an AST or posts an event flag to the process (or both). 


The AST service routine that you specify gains control in process 
context. This routine usually performs one or more of the followina 
steps: 


1. Reads or writes device registers if the process mapped I/0 
space (see Section 4.5). 
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2. Interprets data. Use caution, however, because any 
processing done by the AST service routine can be interrupted 
by a device interrupt, which might store more data or modify 
the buffer's contents. 


3. Calls the Cancel I/O on Channel (SCANCEL) system service to 
disconnect the process from the interrupt. 


4.6.5 Queue I/O Request System Service for Connect-To-Interrupt 


The format of the Queue I/O Request (SQIO) system service to connect 
to an interrupt vector is given below. The explanation is limited to 
connecting to an interrupt vector. For a detailed description of the 
SQIO system service, see the VAX/VMS System Services Reference Manual. 





MACRO Format 


SQIO [efn] ,{chan] ,func ,[iosb] ,[lastadr] ,fastprm] 
r(pl] ,[p2] ,(p3] ,{p4] ,[p5] ,{[pél 


High-Level Language Format 


SYSS$OIO([efn] ,[chan] ,func ,[iosb] ,lastadr] ,fastprm] 
,{pll ,{p2] ,[p3l ,[p4] ,{p5) ,[p6l) 





efn 

iosb 

astadr 

astprm 
These arguments apply to the S$QIO system service completion, not 
to device interrupt actions. For an explanation of these 
arguments, see the S$QIO service description in the VAX/VMS System 
Services Reference Manual. 

func 
Function code of I0$ CONINTREAD or IO$_CONINTWRITE. The 
IO$_CONINTWRITE function code allows locations in the buffer 
pointed to by the Pl argument to be modified; the IOS _CONINTREAD 
function code makes the buffer contents read-only. 

pl 
Address of a descriptor for the buffer containing code and/or 
data. The first longword records the number of bytes in the 
buffer; the second longword records the address of the buffer. 
(Note: The buffer size must not exceed 64K bytes.) 

p2 


Address of an entry point list. The list consists of four 
longwords that contain offsets into the buffer (specified in the 
Pl argument) of entry points of process-specified routines. 
These longwords and their contents are as follows: 


CINSL INIDEV Offset to device initialization routine 
CINSL START Offset to start device routine 

CINSL ISR Offset to interrupt service routine 
CINSL CANCEL Offset to cancel I/O routine 


Note: Symbols starting with CINS are defined by the SCINDEF 
macro. The definitions are in the library SYSSLIBRARY:LIB.MLB. 
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p3 


p4 


p5 


ph 
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Longword containing flags and an optional event flag number 
specification. The low-order word contains the logical OR of 
flags describing options to the connect-to-interrupt facility. 
The flags and their meanings are as follows: 


CINSM EFN Set event flag on interrupt 

CINSM USECAL Use CALL interface to  process-specified 
- routines (default is JSB interface) 

CINSM REPEAT Leave process connected to the interrupt 
iz vector until the connection is canceled 


CINSM INIDEV Process~specified device initialization 
im routine is in the buffer specified in the Pl 
argument 
CINSM START Process-specified start I/O routine is in 
~ buffer 
CINSM_ISR Process-specified interrupt service routine 


is in buffer 
CINSM_CANCEL Process-specified cancel I/O routine is in 
buffer 


The high-order word specifies the number of the event flag to be 
set when an interrupt occurs. This number is expressed as an 
offset to CINSV_EFNUM. 


For example, to specify that your interrupt service routine is in 
the buffer and to set event flag 4, code P3 as follows: 


P3 = CINSM_ISR!ICINSM_EFN!4@CINSV_EFNUM> 


See the "Notes" later in this section for additional information 
on the flags. 


Address of the entry mask of an AST service routine to be called 
as the result of an interrupt. 


AST parameter to be passed to the AST completion routine (used as 
the AST parameter only if the process~-supplied interrupt service 
routine does not overwrite the value). 


Number of AST control blocks to preallocate in anticipation of 
fast, recurrent interrupts from the device. 


Return Status 


SS$ NORMAL 


System service successfully completed. 


ss$ ACCVIO 


The caller does not have the appropriate access to the buffer 
specified in the Pl argument or to the entry point list specified 
in the P2 argument. 
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SS$_BADPARAM 
The size of the buffer specified in the Pl argument exceeds 64K 
bytes, or the number of preallocated AST control blocks specified 
in the P6 argument exceeds 65767. 

SS$ DISCONNECT 


A connection is already outstanding for the device, or a 
condition described in note 2.b (see "Notes") has occurred. 


SS$_EXQUOTA 


The process has exceeded its direct I/O limit quota or its AST 
limit quota. 


SS$_ILLEFC 
An illegal event flag number was specified. 
SS$_INSFMEM 


Insufficient system dynamic memory is available to complete’ the 
system service. 


SS$_INSFSPTS 
Insufficient system page table entries are available to double 
map the process buffer. (The value of the REALTIME SPTS 
parameter to the SYSGEN utility must be increased.) 

SS$_NOPRIV 


The process does not have the CMKRNL privilege. This privilege 

is only required if the user specifies a buffer to be used by the 

process and the process-specified kernel mode routines. 
SS$_UNASEFC 


The process is not associated with the cluster containing the 
specified event flag. 


Privilege Restrictions 
The connect-to-interrupt S$QIO call does not require privileges if 
no shared buffer is specified. If the request specifies a buffer 
descriptor argument, the process must have the CMKRNL privilege. 


Resources Required/Returned 


A connect-to-interrupt request updates the process quota values 
as follows: 


@ Subtracts the number of preallocated AST control blocks in the 
P6 argument from the number of outstanding ASTsS remaining for 
the process (ASTCNT) 


e Subtracts 1 (for the $QIO) from the direct I/O count (DIOCNT) 


Notes 


4.6.6 
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After the SOQIO call is issued, the operation is not completed 
until the process or the connect-to-interrupt driver cancels 
I/O on the channel. 


The connect-to-interrupt driver can cancel I/O on the channel 
for a number of reasons, including the following: 


a. The driver cannot set the specified event flag, perhaps 
because the process disassociated from the common event 
flag cluster after requesting that a flag in that 
cluster be set. 


b. The driver cannot reallocate AST control blocks quickly 
enough. This condition can occur because not enough AST 
control blocks (P6 argument) were specified, because not 
enough pool space is available for the requested AST 
control blocks, or because the process ASTCNT quota is 
exhausted. 


c. The driver cannot queue the AST to the process. 


If no event flag setting was requested in the P3 argument and 
if no AST service routine was specified in the P4 argument, 
P6 if ignored and no AST control blocks are preallocated. If 
you requested an event flag be set and/or an AST service 
routine but did not preallocate any AST control blocks (that 
is, P6 is zero), one AST control block is automatically 
preallocated, because the system needs one control block to 
set any event flag or to deliver any ASTs. 


If you request an event flag and/or an AST service’ routine 
and if you preallocate any AST control blocks, the 
CINSM REPEAT bit is set automatically in the longword 
specified in the P3 argument. Thus, as long as you 
preallocate any AST control blocks, your’ process will 
automatically remain connected to the interrupt vector to 
receive repeated interrupts until the process is disconnected 
from the interrupt vector. 


If the CINSM_REPEAT flag is not set, the process is 
disconnected from the interrupt vector after the first 
successful interrupt, and a status code of SS$_NORMAL is 
returned. 


Conventions for Process-Specified Routines 


Any routines that the process specifies in the connect-to-interrupt 
call are double-mapped, once in process space and once in system 


space. 
e@ 
e 


Each routine executes in kernel mode at an appropriate IPL: 


Device initialization routine after power recovery - IPL 31 


(IPLS POWER) 


Start I/O routine - IPL & (IPLS QUEURAST) 
Interrupt service routine - device IPL (assumed to be IPL 22) 
Cancel routine - IPL 6 (IPL$_ QUEUEAST) 


The process must have the CMKRNL user privilege. 
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Each routine must: 


@ Be position independent 

Follow the rules for accessing I/O space (see Section 4.5.3) 

@ Access only data within the buffer or non-pageable locations 
in system space 

e Perform any necessary Synchronization of access to data in the 
shared buffer 


e Save any registers it uses (unless otherwise noted in _ the 
remaining sections of this chapter) 

e Exit properly 

e Not incur exceptions 

e Not perform lengthy processing 

e Not dispatch to code outside the buffer specified in the Pl 


argument to the Queue I/O Request call 


Sections 4.6.8 through 4.6.11 discuss conventions for specific process 
specified routines. Section 4.6.12 describes several program examples 
of connecting to an interrupt vector. 


The VAX/VMS Guide to Writing a Device Driver explains how to write a 
device initialization routine, a start I/O routine, an interrupt 
service routine, and a cancel I/O routine. That manual also discusses 
the I/O data structures used by these routines. 





4.6.7 Programming Language Constraints 


Only VAX-11 MACRO or VAX-11 BLISS-32 should be used _ to code 
process-specified routines in system space (see Section 4.6.6) or any 
references to I/O space. There is no assurance that the code 
generated by compilers for other languages will satisfy all the 
constraints described in this section. 


The following constraints apply to process-specified routines in 
system space (that is, in the buffer specified in the Pl argument to 
the $QIO call that establishes the connection to the interrupt 
vector): 


e The compiler must generate position independent code for the 
routines. 


e The generated code and data must be contiguous in virtual 
space, 


e No calls can be made to any procedure outside the buffer. 
(This restriction includes calls to routines in the VAX-11 
Common Run-Time Procedure Library.) 


For any references to I/O space, the generated code must follow’ the 
rules for accessing I/O space (see Section 4.5.2). Device register 
access from high-level languages usually requires that the variable 
equivalent to the register be a 16-bit integer data type. You may 
need to check the assembly~language code generated by compilers’ for 
languages other than VAX-11 MACRO or VAX-11 BLISS-32 to determine 
whether it follows all necessary conventions. 
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4.6.8 Process-Specified Device Initialization Routine 


During recovery from a power failure, VAX/VMS calls the 
connect-to-interrupt driver's device initialization routine. This 
routine marks the device as online in the UCBSW STS field, stores the 
UCB address in the IDBSL_OWNER field, and then transfers control to 
the process~specified device initialization routine, The 
process-specified routine executes in system context at IPL 31 
(IPL$_POWER). 


If the process specified a JSB interface, the process routine gains 
control with the following register settings: 


RO address of the unit control block (UCB) 

R4 address of the device status register (CSR) 
R5 address of the interrupt dispatch block (IDB) 
R6 address of the device data block (DDB) 

R8 address of the channel request block (CRB) 


If the process specified a CALL interface, the process routine gains 
control with an argument list pointed to by AP: 


O(AP) argument count of 5 

4(AP) address of the device status register (CSR) 
8(AP) address of the interrupt dispatch block (IDB) 
12(AP) address of the device data block (DDB) 

16(AP) address of the channel request block (CRB) 
20(AP) address of the unit control block (UCB) 


The process-specified routine may initialize device registers. 
However, it must not lower IPL, and it must preserve all registers 
except RO through R3. 


The routine exits with an RSB instruction (for a JSB interface) or a 
RET instruction (for a CALL interface). The stack must be as it was 
when the routine was entered. 


4.6.9 Process-Specified Start I/O Routine 


The process-specified start I/O routine executes in system context at 
IPL 6 (IPLS QUEUEAST). It is entered from the connect~-—to-interrupt 
driver's start I/O routine. The input to the process-specified start 
I/O routine is as follows: 


R2 address of the counted argument list 
R3 address of the I/O request packet (IRP) 
R5 address of the unit control block (UCB) 


O(AP) argument count of 4 

4(AP) system-mapped address of the process buffer 
8(AP) address of the I/O request packet (IRP) 
12(AP) system-mapped address of the device's CSR 
16(AP) address of the unit control block (UCB) 


The process-specified start I/O routine may set up device registers. 
It can raise IPL but must not lower it below 5, and must exit at IPL 
6. It must preserve all registers except RO through R4. 


The routine exits with an RSB instruction (for a JSB interface) or a 
RET instruction (for a CALL interface). The stack must be as it was 
when the routine was entered. 
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4.6.10 Process-Specified Interrupt Service Routine 


A process~specified interrupt service routine is entered when an 
interrupt from the device occurs. This routine executes in system 
context at device IPL. The input to the process-specified interrupt 
service routine is as follows: 


R2 address of the counted argument list 
R4 address of the interrupt dispatch block (IDB) 
R5 address of the unit control block (UCB) 


O(AP) argument count of 5 

4(AP) system-mapped address of the process buffer 

8(AP) address of the AST parameter 

12(AP) system-mapped address of the device status register (CSR) 
16(AP) address of the interrupt dispatch block (IDB) 

20(AP) address of the unit control block (UCB) 


This routine is responsible for clearing the interrupt condition (by 
writing to some device register, for example) if such an operation is 
required for the device. In addition, the routine may copy’ the 
contents of device registers into the shared buffer or into the AST 
parameter. The routine must also follow these conventions: 


e Maintain an IPL equal to or higher than device IPL (If the IPL 
is raised, the current IPL should first be saved on the stack 
for later use in restoring IPL.) 


@ Save and restore all registers other than RO through R4_ used 
in the routine 


e Restore the stack to its original state before exiting 
e Place one of the following status values in RO before exiting: 


low bit clear -- dismiss interrupt (process is not notified of 
interrupt) 


low bit set -- set event flag if CINSM_EFN bit is set in P3 
argument, and queue AST if P4 specifies an 
AST service routine 


e Exit with a RET instruction (CALL interface) or RSB 
instruction (JSB interface) 


4.6.11 Process-Specified Cancel I/O Routine 

When the user process issues a cancel I/O request for a device 
connected to the process, the connect-to-interrupt driver's cancel I/0 
routine first checks to determine whether the process can indeed 
cancel I/O for this device. If it can, the process-specified cancel 
I/O routine is given control. This routine executes in system context 
at IPL 8 (IPLS_FORK). 


If a JSB interface was specified for the process-supplied cancel I/0 
routine, the following registers are inputs: 


R2 negated value of the channel index number 

R3 address of the current I/O request packet (IRP) 

R4 address of the process control block (PCB) for the process 
canceling the I/O 

R5 address of the unit control block (UCB) 
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If a CALL interface was specified, the argument list is as follows: 


O(AP) argument list count of 4 

4(AP) negated value of the channel index number 

8(AP) address of the current I/O request packet (IRP) 

12(AP) address of the process control block (PCB) for the process 
canceling the I/0 

16(AP) address of the unit control block (UCB) 


The process~-specified cancel I/O routine must not lower IPL below 6 
and must exit at IPL 6. It may clear device registers. It must 
preserve all registers except RO and R3, and must place a completion 
status in RO-R1l (which VAX/VMS will place in the I/O status block 
associated with the connect-to-interrupt SQIO call). 


The process-specified cancel I/O routine should not rely on_ the 
channel index number unless it checks the UCBSM BSY bit in UCBSW STS 
to confirm that the process is still connected to the device. ~The 
routine may set the UCBSM CANCEL bit in UCBSW_ STS. 


The routine exits with an RSB instruction (for a JSB interface) or a 
RET instruction (for a CALL interface). The stack must be as it was 
when the routine was entered. 


4.6.12 Real-Time Applications Examples 


To understand how the connect-to-interrupt facility is useful for 
programming real-time devices, consider devices used in three types of 
real-time applications: 


1. Asynchronous event reporting without data: devices that 
generate an interrupt as the result of an external event not 
initiated by a programmed request. 


2. Program-driven data collection: devices that generate an 
interrupt as the result of a programmed request, and make the 
result of the request available as data in a device register 
at the time of the interrupt. 


3. Asynchronous event reporting with data: one device triggers 
another device by generating an interrupt that causes a 
programmed request to be sent to the other device, which in 
turn generates an interrupt. 


Examples of these three types of real time applications and models of 
programs to handle the devices follow. 


NOTE 
The configurations described in the 
examples in this section are not 
officially supported; DIGITAL does not 
provide device driver, UETP, or 
diagnostic support for certain devices 
mentioned. The examples are provided 


merely as poSsSible models for users who 
wish to design real-time applications 
using unsupported devices or 
configurations. 
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Chapter 6 contains a program example illustrating data definitions and 
coding used to connect to a device interrupt vector. 


4.6,12.1 Example 1: KW1l1l-W Watchdog Timer - This type of device 
reports asynchronous external events: it generates an interrupt as a 
result of an external event not initiated by a programmed request. 
The only data of interest to be passed to the user process is the 
occurrence of the external event. Such devices include contact and/or 
solid state interrupts, and clocks or, counters. The program may need 
to initiate clock and counter devices by means of a programmed 
request, but any subsequent interrupts are the result of external 
events only. 


In this example, a dual-processor system uses two KW1l1-W watchdog 
timers connected back-to-back to monitor CPU failures. Each processor 
must arm its timer at regular intervals to prevent the timer from 
operating a relay that outputs an alarm signal. The alarm output of 
each timer is connected to the receive input of the other watchdog. 
If processor A fails and its watchdog times out, the alarm output 
generates an interrupt on processor B via the second watchdog timer. 


The watchdog control program on each processor simply addresses the 
timer at regular intervals. If the interval passes without the timer 
being addressed, the timer operates an output relay that generates an 
interrupt to the second CPU. For this example, assume that the 
interval is 5 seconds (Example 3 later in this section addresses’ the 
problem of a much smaller time interval). 


The watchdog control program on processor A executes as follows: 
1. Assigns a channel to the device 


2. Calls S$CRMPSC to map to the I/O page in order to address’ the 
device registers 


3. Issues a connect-to-interrupt S$QIO call to connect’ the 
program to the watchdog timer for processor B; specifies the 
addresses of an interrupt service routine and an AST routine 


4. Writes a value to a device register to start the timer 


5. Calls SSETIMR to request that an event flag be set after a 
specified interval (for example, 5 seconds) 


6. Calls SWAITFR to wait for the event flag 


7. When the event flag is set, writes a value to a device 
register to reset the timer 


8. Loops to step 5 


The same control program runs on processor B except that it connects 
to the watchdog timer for processor A. If either processor fails, the 
watchdog timer generates an interrupt on the other processor. 


The standby processor that receives the interrupt gains control in the 
VAX/VMS connect-to-interrupt driver (CONINTERR), which calls a 
process-Supplied interrupt service routine (defined in step 3 ahove) 
that handles the interrupt as follows: 


1. Sets the KW1l1l-W switch relay register to clear the timer 
interrupt condition 


PERFORMING I/0 OPERATIONS 


2. Sets a status flag that will cause an AST to be delivered to 
the control program that connected to the interrupt 


3. Returns to CONINTERR 
CONINTERR completes the interrupt handling as follows: 


1. Schedules a fork process at a lower IPL. This fork process, 
when it gains control, will queue an AST to the user program, 


2. Executes an REI instruction to return from the interrupt 


The timer control program on the standby processor regains control in 
an AST routine. This routine responds to the other processor's 
failure by switching over and assuming control of the other 
processor's tasks (or whatever is appropriate). 


4,.6.12.2 Example 2: AD11-K, AM11-K; A/D Converter with Multiplexer 
Connected to the UNIBUS ~ This type of device provides program-driven 
data collection: it generates an interrupt as the result of a 
programmed request to the device, and makes the result of the request 
available as data in a device register. Typical devices include A/D 
converters and digital I/O registers. 


The data collection operation is usually repetitive for such 
applications. Therefore, the interrupt service routine must be 
capable of buffering data from the device in order to ensure that no 
data is lost due to the high speed data transfer rate. A typical 
buffer size for this sampling technique might be 32 16-bit words. 


In this example, a user program controls an AD11-K/AM11-K combination 
that accepts analog data from thermocouples. The AD11-K converts 
analog data to digital data and returns the data in a device register. 
Every 10 seconds, the program samples 15 to 32 out of 64 channels at 
gain settings that may vary based on the thermocouple type and 
previous samplings. 


To collect data efficiently, the program buffers data in a 
process-specified interrupt service routine, and requests delivery of 
an AST to the user process when all the requested channels have _ been 
sampled. To perform variable sampling, the program passes parameters 
to the interrupt service routine. 


The program establishes a protocol to communicate between the program 
and the interrupt service routine. The protocol defines a data area 
shared by the main program, the interrupt service routine, and the AST 
routine. The data area contains parameters from the program and data 
from the AD1I-K. The data area is a 98-word array used as follows: 


l. Elements 1-2 of the data area contain an index to the next 
buffer location to be filled, and a count indicating the 
number of samplings still to be taken. The main program 
initializes these values before starting the device. The 
interrupt service routine reads and modifies these values in 
the process of copying data and determining when to stop 
Sampling. 


2. Elements 3-66 of the data area are reserved for interrupt 
service routine parameters. Each pair of elements contains 
the number of a channel, and a gain value. The main ‘program 
loads these parameters before starting the device. 
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3. Elements 67-98 of the data area receive the data that the 
interrupt service routine reads from the AD11-K data buffer 
register. The AST routine later. reads data from this part of 
the buffer. 


The program sets up for the sampling as follows: 
1. Assigns a channel to the device 


2. Calls SCRMPSC to map to the I/O page in order to address’ the 
device registers 


3. Initializes the data area by writing a 67 (the index to the 
next buffer location to be filled) into element 1, and the 
number of samples to take into element 2 of the data area; 
zeroes elements 3-98 of the data area 


4. Writes channel numbers and gain values into the parameter 
section of the data area 


5. Issues a connect-to-interrupt S$QIOQ call to connect’ the 
process to the A/D converter; specifies the addresses of the 
area to be double mapped, an offset to the ISR, and an AST 
routine 


6. Sets the start and interrupt enable bits in the AD11-K status 
register to start the A/D converter 


7. Calls SHIBER to place the process in a wait state 


AS soon as the AD11-K has converted the first sample, the device 
generates an interrupt. The VAX/VMS CONINTERR- routine calls the 
process-specified interrupt service routine. This process-specified 
routine executes as follows: 


1. Computes the next location to be written in the buffer by 
reading the first element in the data area 


2. Reads 12 bits of data from the A/D buffer register into the 
next location in the buffer 


3. Updates the buffer offset and count elements at the beginning 
of the data area 


4. If all requested samples have been collected, writes the 
address of the data area into the AST parameter, sets a 
status flag that will cause an AST to be delivered to _ the 
control program, and returns to the CONINTERR routine 


5. Otherwise, sets the start bit in a device register to restart 
the device and returns to the CONINTERR routine with a status 
flag requesting no AST delivery or event flag setting 


Based on the interrupt status from the process-specified interrupt 
service routine, the CONINTERR routine completes the interrupt 
processing by queuing a fork process that will queue an AST to. the 
user process, When the process gains control in the AST service 
routine, this routine processes the samples in the following steps: 


1. Clears the interrupt enable bit in the device status register 


2. Examines the data collected in order to adjust channel 
selection and/or gain values for the next sampling 
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3. Copies the data to a file 
4. Reinitializes the data area 


5. Calls S$SCHDWK to wake the process after a short interval (for 
example, 10 seconds) 


6. Returns 


When the time interval elapses, the process regains control. The 
program can then restart the sampling process by again setting the 
Start and interrupt enable bits in the AD11-K status register. 


4.6.12.3 Example 3: KW11-P Real Time Clock and AD11-K Converter 
Connected to the UNIBUS - This’ type of device reports asynchronous 
external events by collecting data: one device triggers another 
device by generating an interrupt that causes a programmed request to 
be sent to the other device, which in turn generates an interrupt. A 
typical example is a clock-driven A/D operation for precise time 
sampling as required in signal processing. This processing technique 
is often used in laboratories. The amount of data collected in such a 
timed sampling might typically be 200 to 1000 16-bit words. 


In this example, the main program sets up the real-time clock to 
generate interrupts periodically. At reqular intervals, the clock 
interrupt triggers a programmed request for an A/D conversion 
operation. The AD11-K collects a sample, and interrupts the CPU with 
a "done" interrupt and 12 bits of data. The AD11-K interrupt service 
routine buffers the data and, if the buffer is full, causes an AST to 
be delivered to the process. The process, gaining control in an AST 
routine, copies the buffered data to another buffer or to disk. 


Programming these device functions is slightly more complicated than 
the previous example. The main program must specify a large buffer to 
be used in ring fashion to guarantee that data is not lost hetween 
clock-driven samplings. In addition, the program must connect to two 
device interrupts -- one for the clock and one for the A/D converter. 


The protocol used by the main program, the interrupt service routine, 
and the AST routine is similar to the previous example. The data area 
is larger: 4K words of buffer area follow the parameter area. The 
A/D converter interrupt service routine and the AST routine treat the 
4K-word buffer as four buffer sections of 1K words per’ section. The 
first element in each 1K buffer section is a flag indicating whether 
the section is in use. The AST resets the flag value after copying 
the contents of the buffer. The interrupt service routine uses a 
buffer section only if the section's flag value indicates that the 
buffer has been emptied. 


The main program starts the sampling with the following steps: 
1. Assigns channels to the clock and to the A/D converter. 


2. Calls SCRMPSC to map to the I/O page in order to address’ the 
device registers. 


3. Initializes the data buffer by writing a 57 (the index to the 
next buffer location to be filled) into element 1, and the 
number of samples to take into element 2 of the data area; 
zeroes elements 3-4096 of the data area; flags each page of 
the buffer as available. 


9. 
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Writes channel numbers and gain values into the parameter 
segments of the data area. 


Issues a connect-to-interrupt SQIO call to connect’ the 
process to the clock, and specifies the address of an 
interrupt service routine, — 


Issues a connect-to-interrupt $QIO0 call to connect’ the 
process to the A/D converter; and specifies the addresses of 
the area to be double mapped, an offset to the interrupt 
service routine and an AST routine, 


Sets the sampling interval by writing a 16-bit value into the 
KW11-P count set buffer register. 


Starts the clock by setting the run, mode, rate selection, 
and interrupt enable bits in the KW11-P control and status 
register. Setting the mode bit causes repeated interrupts 
generated at a rate specified in the time interval. 


Calls SHIBER to place the process in a wait state. 


The clock interrupts when zero (underflow) occurs during a count-down 


from the 


preset interval count. The VAX/VMS CONINTERR routine calls 


the process-specified clock interrupt service routine. This 
process~specified routine starts the A/D conversion as follows: 


1. 


2. 


3. 


Starting 


Starts the A/D converter by setting the start and interrupt 
enable bits in the AD11-K status register 


Sets interrupt status that prevents AST delivery or event 
flag setting as a result of this interrupt 


Returns to CONINTERR 


the A/D converter results in an interrupt from the AD11-K, 


and control passes, via CONINTERR, to the AD11-K interrupt service 


routine. 


1. 


This routine executes as follows: 


If this sample is the first sample for a new buffer 
(indicated by a flag in the data area), the routine moves to 
the next buffer section (branches to error handling if the 
buffer is still full), and sets up the first two elements of 
the data area to indicate the buffer section to be written 
next. Then, it sets the flag at the start of the new buffer 
section and sets a flag in the data area to indicate that 
sampling is occurring. 


The routine computes the next location to be written in the 
buffer by reading the first location in the data area, 


The routine reads 12 bits of data from the A/D buffer 
register into the next location in the buffer. 


The routine updates the buffer offset and count values in the 
data area. 


If this sample fills the data sector, the routine writes’ the 
offset of the filled sector from the start of the 4K-word 
buffer into the AST parameter, sets a status flag that will 
cause an AST to be delivered to the control proaram, and sets 
a. flag indicating that a new data section is to be started, 


The routine returns to CONINTERR. 
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The AST routine copies and zeroes the next buffer section to indicate 
that the section is again available to the interrupt service routine. 
When the next clock interrupt occurs, the data can be written to the 
next buffer section, even if the AST routine has not yet emptied the 
previous buffer section. 


CHAPTER 5 


USING SHARED MEMORY 


The MA780 is a multiport memory unit that can be attached to 
VAX-11/780 processors. Bach VAX-11/780 processor can support up to 
two MA780s. Each MA780 has four ports, thereby allowing up to four 
VAX-11/780 processors to be attached to it. Figure 5-1 illustrates 
two VAX-11/780 processors attached to an MA780. 


MA780 
MULTIPORT 





Figure 5-1 Two VAX-11/780s Attached to an MA780 


Using one or more multiport memory units, an application can consist 
of multiple processes running on different VAX-11/780 processors. 
Regardless of the processor on which they are running, these processes 
can communicate the completion of an event, send messages, and share 
common data and code by means of the shared memory. 


5.1 PREPARING MULTIPORT MEMORY FOR USE 


Before an application using multiport memory can execute under 
VAX/VMS, the system manager must activate the VAX/VMS operating system 
in processors connected to the multiport memory unit and initialize 
that memory. The VAX/VMS System Manager's Guide explains the system 
Management responsibilities associated with a multiport memory unit; 
the present section summarizes the system management functions for the 


benefit of the application programmer. 





First, the system manager activates the VAX/VMS operating system in a 
VAX-11/780 and initializes the multiport memory unit. These actions 
cause the following to occur: 


e The uninitialized shared memory is connected to the VAX/VMS 
system running in the processor. 
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e A name is defined that all processes running in all processors 
can use to refer to the shared memory (see Section 5.3) 


e Limits are set for the following resources in this multiport 
memory unit: 


~ Common event flag clusters: the total number that can 
be created, and the number that can be created by 
processes running on this processor 


- Mailboxes: the total number that can be created, and 
the number that can be created by processes running on 
this processor 


- Global sections: the total number that can be 
created, and the number that can be created by 
processes running on this processor 


Then the system manager activates the VAX/VMS operating system in 
other processors connected to the multiport memory unit. The system 
manager then connects the initialized shared memory to the VAX/VMS 
system running in each of these processors and sets limits for the 
number of common event flag clusters, global sections, and mailboxes 
that processes on each processor can create in the multiport memory. 


The system manager can also install global sections in shared memory 
just as they are installed in local memory. The INSTALL utility can 
be used to create shared memory global sections for known files. Once 
the global sections are installed, a process running in any processor 
connected to the multiport memory can map to the section, if the 
process has the appropriate privilege. The process can gain access to 
the global section either by using a logical name defined by the 
system manager or by using the section name specified when the global 
section was created. In the latter case, the section name must be 
unique on this processor. 


5.2 PRIVILEGES REQUIRED FOR SHARED MEMORY USE 


To use facilities in memory shared by multiple processors, you must 
have all of the user privileges required to use the equivalent 
facility in local memory. For example, to create a permanent global 
section, you must have the PRMGBL privilege, and to create a temporary 
or permanent mailbox, you must have the TMPMBX or PRMMBX privilege, 
respectively. 


In addition to any other required privileges, you must have the SHMEM 
privilege to create or delete a common event flag cluster, mailbox, or 
global section in memory shared by multiple processors. However, you 
do not need the SHMEM privilege to uSe an existing cluster, mailbox, 
or global section in multiport memory. 


5.3 NAMING FACILITIES IN SHARED MEMORY 


To allow access to facilities in memory shared by multiple processors, 
the system manager and application -programmers define names that 
application programs use to refer to individual shared memory units. 
During system installation, the system manager defines the name that 
processes on that particular processor use to refer to the shared 
Memory itself. Application programs define the names that they use to 
refer to common event flag clusters, global sections, and mailboxes 
located in the shared memory. 
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By convention, facilities in shared memory have a name string in the 
following format: 


{memory~name: ]facility-name 


memory-name 


Name assigned by the system manager during system installation to 
the shared memory containing the facility. VAX/VMS requires the 
memory name when you specify a common event flag cluster or 
mailbox. The colon is recognized as a delimiter separating the 
two parts of the name string. 


facility-name 


Logical name assigned to the event flag cluster, global section, 
or mailbox. The name must contain 15 or fewer characters, and 
can consist only of alphabetic characters, numeric characters, 
the dollar sign (S$), and the underline (_). 


Examples of facility names are: 


SHRMEM:GS_DATA Identifies the qlobal section GS_DATA in the 
shared memory named SHRMEM 


SHRMEM: MAILBX Identifies the mailbox MAILBX in the same 
shared memory 


5.4 ASSIGNING LOGICAL NAMES AND LOGICAL NAME TRANSLATION 


You can define a logical name for a shared memory facility with the 
DEFINE or ASSIGN command or the Create Logical Name (SCRELOG) system 
service, Application programs can then refer to the facility using 
the logical name; for example, a process can invoke the Create 
Mailbox and Assign Channel ($CREMBX) system service specifying the 
logical name for an existing mailbox to which a channel is to be 
assigned. 


When translating a logical name for a shared memory facility, the 
VAX/VMS operating system uses a Slightly different approach from that 
used for other logical names. The purpose of this approach is to 
allow programmers to specify either the complete name (memory name and 
facility name) or a logical name that the system will translate to the 
complete name. If you define logical names properly, a program that 
uses a given facility in local memory can be run without change to use 
the facility in shared memory. 


Whenever VAX/VMS encounters the name of a common event flag cluster, 
mailbox, or global section, it performs the following special logical 
name translation sequence: 


1. Inserts one of the following prefixes to the name (or to’ the 
part of the name before the colon if a colon is present): 


CEFS for common event flag clusters 
MBXS for mailboxes 
LIBS for global sections 
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2. Subjects the resultant string to logical name translation. 
If translation does not succeed (that is, the original name 
did not use a logical name), passes the original name. string 
to the system service. If translation does succeed, goes to 
step 3. 


3. Appends the part of the original string after the colon (if 
any) to the translated name. 


4. Repeats steps 1 to 3 (up to nine more times, if necessary) 
until logical name translation fails. When translation 
fails, passes the string to the system service. 


For example, assume that you have made the following logical name 
assignment: 


$ DEFINE MBXSCHKPNT SHRMEMS1:CHKPNT 


Assume also that your program refers to the mailbox name as CHKPNT in 
a system service argument. The following logical name translation 
takes place: 


1. MBXS is prefixed to CHKPNT,. 
2. MBXSCHKPNT is translated to SHRMEMS1:CHKPNT. 


3. No further translation is successful; therefore, the string 
SHRMEMS1:CHKPNT is passed to the system service. 


The logical name definition in the preceding example allows a program 
that used a mailbox named CHKPNT in local memory to run using the 
mailbox in shared memory, without being recompiled or relinked. 


Note that if a process creates one or more subprocesses and they uSe a 
mailbox or common event flag cluster in shared memory, the creator 
should place the logical name in the group logical name table (for 
example, specify the /GROUP qualifier with the DEFINE command). If 
the name is defined in the process logical name table (the default), 
the subprocesses will not receive the correct equivalence name, 
because each subprocess has its own process logical name table. 


There are two exceptions to the logical name translation method 
discussed in this section: 


e If the facility name starts with an underline ( ), the VAX/VMS 
system strips the underline and considers the resultant string 
to be the actual name (that is, no further translation is 
performed). 


e If the facility is a global section with a name in the’ format 
name nnn, VAX/VMS’ first strips the underline and the digits 
(nnn), then translates the resultant name according to the 
sequence discussed in this section, and finally reappends the 
underline and digits. The system uses this method with known 
images and shared files installed by the system manager. 
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5.5 HOW VAX/VMS FINDS FACILITIES IN SHARED MEMORY 


After the VAX/VMS system performs the logical name translation 
described in Section 5.4, the final equivalence name must be the name 
of a facility in either the processor's local memory or in_ shared 
memory. If the equivalence name specifies the name of a shared memory 
(that is, the name is in the format name:facility-name), VAX/VMS 
searches for the facility in the appropriate data base of the 
specified memory. 


If the equivalence name specifies a common event flag cluster or 
mailbox and does not specify a memory name, VAX/VMS searches through 
the common event flag cluster data base or the mailbox data base until 
it locates the specified cluster or mailbox. Absence of a memory name 
as part of a common event flag cluster name or mailbox name indicates 
that the facility is located in local memory. 


If the equivalence name specifies a global section and does not 
specify a memory name, VAX/VMS looks for the section as follows: 


1. First, it searches the global section tables for sections in 
the processor's local memory. 


2. Then, it searches the global section tables for each 
initialized shared memory connected to the processor in the 
order in which they were connected and recognized by the 
processor, 


The result of searching in this order is that global sections in the 
processor's local memory take precedence over those in shared 
memories. Thus, absence of a memory name as part of a global section 
name is not used as an indication of where the global section is 
located. 


5.6 USING COMMON EVENT FLAGS IN SHARED MEMORY 


Under VAX/VMS, any process can associate with up to two common event 
flag clusters (event flag numbers 64 through 95 and 96 through 127). 
These clusters can be located in shared memory or in local memory. To 
create and associate with a common event flag cluster in shared memory 
and manipulate flags in the cluster, you use the same steps as you 
would to associate with a common event flag cluster in local memory: 


l. Issue the Associate Common Event Flag Cluster (SASCEFC) 
system service to create the cluster or to associate with an 
existing cluster, 


2. Issue any of the services that set, clear, and wait for 
designated event flags, as appropriate. 


As with local memory clusters, the first procesS among cooperating 
Processes to issue the Associate Common Event Flag Cluster (SASCEFC) 
system service causes the cluster to be created. Any other process 
calling this service and specifying the same cluster associates with 
that cluster. VAX/VMS implicitly qualifies cluster names with the 
group number of the creator's UIC; therefore, other cooperating 
processes must belong to the same group. 
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All of the event flag system services, with the exception of Associate 
Common Event Flag Cluster and Disassociate Common Event Flag Cluster, 
function identically regardless of whether they are used with local or 
shared memory clusters, The only difference with the associate and 
disassociate system services is that to specify a cluster in shared 
memory, you must provide the memory name as well as the cluster name. 
That is, after VAX/VMS performs logical name translation of the name 
argument, the cluster name must have the following format: 


memory-name:cluster-name 


Section 5.3 describes the name format, and Section 5.4 explains’ the 
logical name translation performed by the system. 


Section 3.1 discusses common event flags and related system services. 
The VAX/VMS System Services Reference Manual describes all of the 
event flag services in detail. 





5.7 USING MAILBOXES IN SHARED MEMORY 


The first process on each processor to refer to a shared memory 
mailbox must use the Create Mailbox and Assign Channel (SCREMBX) 
system service to create the mailbox and assign a channel to it. Any 
SCREMBX system service call referring to a shared memory mailbox must 
specify a mailbox name that has or translates to the following format 
(Section 5.4 explains the logical name translation procedure): 


memory-—name:mailbox-name 


When the mailbox is created, the SCREMBX system service also creates 
the mailbox-name portion of the name string as a logical name with an 
equivalence name in the format MBn. For example, if the complete name 
string is SHMEM:MAILBOX, the system service will create MAILBOX as a 
logical name with an equivalence name of, for example, MBBOOS. 


The Assign I/O Channel (S$ASSIGN) and Deassign I/0 Channel (SDASSGN) 
system services require that you specify only the mailbox-name portion 
of a shared memory mailbox name string. Likewise, any high-level 
lanquage program statements that open, close, read from, or write toa 
shared memory mailbox must specify only the mailbox-name portion. 


Figure 5-2 shows two VAX-11 FORTRAN programs using a shared memory 
mailbox. The memory-name in this example is SHMEM. The programs are 
running in processes on separate processors. 
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PROGRAM ONE 
INTEGER*4 SYSSCREMBX,STATUS ,CHAN 


STATUS = SYSSCREMBX(,CHAN,,,,,'SHMEM:MAILBOX') 
IF (.NOT. STATUS) CALL LIBSSTOP(%VAL (STATUS) ) 


C-- Open the mailbox using the mailbox-name; write a message. 


OPEN (UNIT=1,NAME='MAILBOX',STATUS='NEW') 
WRITE (1,*) MESSAGE 


END 


PROGRAM TWO 
INTEGER*4 SYSSCREMBX,STATUS ,CHAN 


STATUS = SYSSCREMBX(,CHAN,,,,,'SHMEM:MAILBOX') 
IF (.NOT. STATUS) CALL LIBSSTOP(%VAL (STATUS) ) 


C-- Open the mailbox using the mailbox-name; read the message. 


OPEN (UNIT=1,NAME='MAILBOX',STATUS='OLD') 
READ (1,*) MESSAGE 


END 





Figure 5-2 Using a Shared Memory Mailbox 


A mailbox in shared memory cannot be used as_ process’ termination 
mailbox. 


Section 3.2 discusses mailboxes and related system services, and 
includes a programming example. 


5.8 USING GLOBAL SECTIONS IN SHARED MEMORY 


Under VAX/VMS, processes can map global sections located in local 
memory or in shared memory. A global section in shared memory can be 
mapped to an image file or a data file, just like a global section in 
local memory. To create a global section in shared memory, you 
perform the same steps as you would to create a global section in 
local memory: 


1. Using VAX-11 RMS, open the file to be mapped. 
2. Issue the Create and Map Section (SCRMPSC) system service. 
The file to be mapped must reside on a disk device attached to the 


local processor. Once the section is created, however, processes on 
all processors attached to the shared memory can map the section. 
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To map an existing global section in shared memory, you issue a Map 
Global Section (SMGBLSC) system service specifying the name of the 
section. Once the section is mapped, processes gain access to. shared 
memory global sections in the same manner as they do to local memory 
sections. VAX/VMS thus makes use of the_- shared memory unit 
transparent to the process. 


VAX/VMS treats the pages of a global section in shared memory 
differently from pages in local memory. When a process creates a 
shared-memory global section, VAX/VMS brings all of the pages of the 
mapped image or data file into memory. Any process mapped to that 
global section can gain access to those pages without incurring a page 
fault because the pages are already in physical memory. Unlike 
process pages in local memory, global section pages in shared memory 
are not included in the working sets of the processes that map the 
section. 


Because no paging occurs, VAX/VMS never writes the contents of shared 
memory global section pages back to their disk file. For read/write 
global sections in which you want to maintain an updated file while 
the application executes, you must issue an Update Section File on 
Disk (SUPDSEC) system service. The process issuing the update request 
must execute on the same processor as the process that created the 
global section. You can update the disk file periodically during 
execution of the application as a checkpoint precaution. The disk 
file is automatically updated when the section is deleted. 


Each process that has mapped a global section in shared memory can 
unmap the section in either of the following ways: 


e Issue a Delete Virtual Address Space ($DELTVA) system service 
to delete the process's virtual address space that maps the 
section. 


e Terminate the current image, thereby causing VAX/VMS to unmap 
the process from the section automatically. 


Deleting a global section in shared memory requires an explicit 
deletion request, because all global sections in shared memory must be 
permanent sections. The deletion request can be either a Delete 
Global Section ($DGBLSC) system service issued by the application or a 
deletion request issued by the system manager. In either case, 
VAX/VMS does not perform the actual deletion until all processes that 
have mapped the section unmap it. 


The VAX/VMS System Services Reference Manual provides information on 
the use of the VAX/VMS system services used with global sections, that 
is, memory Management system services. Section 5.8.1 of the present 
manual provides information specifically related to creating and 
mapping a global section in shared memory. The SCRMPSC, SMGBLSC, 
SDGBLSC, and SUPDSEC system services are the only memory management 
system services for which the shared memory has any direct 
implications. 





5.8.1 Create and Map Section System Service 


The Create and Map Section System Service has the following gqeneral 
formats when issued to create and/or map a global section in multiport 
memory. 
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MACRO Format 


SCRMPSC [inadr], {retadr], [acmode], {flags], gsdnam 
,{ident], [relpag], [chan], [pagent], [vbn], [prot] 


High-Level Language Format 


SYSSCRMPSC (finadr], [retadr], f[acmode], [flags], gsdnam 
,({ident], [relpag], [chan], [pagent], [vbn], [prot]) 


With the exception of the FLAGS, GSDNAM, and PFC arguments, the 
arguments of this service are not affected by MA780 considerations. 


flags 


Mask defining the section type and characteristics. Of the flags 
defined, the following two must be set. 


Flag Meaning 
SECSM_GBL Global section 
SECSM_PERM Permanent section 


That is, sections in shared memory must be permanent global 
sections. 


If appropriate, the following flags also can be Set. 


Flag Meaning Default 

SECSM_DZRO Pages are demand- Pages are not zeroed 
zero pages when copied 

SECSM_WRT Read/write section Read-only 

SECSM_SYSGBL System global Group global section 
section 

SECSM_EXPREG Map section Map section according 
into the to the INADR argument 


first free range 
of virtual 
addresses large 
enough to hold 
the section 


Neither SECSM CRF (copy-on-reference) nor SECSM PFNMAP- (page 
frame number mapping) can be set when using the Create and Map 
Section system service to create global sections in _ shared 
memory. If SECSM CRF is set, VAX/VMS places the global section 
in local memory. ~ 


gsdnam 


Address of a character string descriptor pointing to the text 
name string for the global section. This argument is required 
for creating sections in Shared memory. 


The string can be either the name of a global section or _ the 
logical name of a global section. VAX/VMS performs logical name 
translation as described in Section 5.4. 


pfc 
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VAX/VMS implicitly qualifies global section names’ with an 
identification. For group global sections, the section name is 
also implicitly qualified by the group number of the _ process 
creating the global section. 


Page fault cluster size for local memory sections. This argument 
is ignored for global sections in shared memory, because VAX/VMS 
reads the file into memory when it creates the section and does 
not allow paging for sections in shared memory. 


CHAPTER 6 


PRIVILEGED SHAREABLE IMAGES 


A privileged shareable image is a shareable image containing one or 
more routines that nonprivileged users can call to perform privileged 
functions. The creator of the privileged shareable image codes, 
compiles or assembles, links, and installs the routine; other users 
can then call this routine in their programs using the standard CALL 
interface, provided they have linked their object module(s) with the 
privileged shareable image. Privileged shareable images thus’ provide 
a vehicle for users, in effect, to write and use their own system 
services. 


Because privileged shareable images can be written for any purpose, 
their use is not limited to real-time applications. However, 
privileged shareable images can provide real-time users with a 
suitable vehicle for special-purpose routines that nonprivileged 
processes in applications can uSe. 


6.1 CODING THE PRIVILEGED SHAREABLE IMAGE 


The following requirements must be met in coding a_ privileged 
shareable image: 


e It must contain a special change-mode vector identifying a 
kernel-mode and/or executive-mode dispatcher. 


e Its entry point must be followed by a CHMK or CHME instruction 
with a negative operand. 


e Any kernel-mode or executive-mode dispatcher pointed to in the 
change-mode vector must validate the CHMK or CHME operand, and 
must be followed by one or more routines that perform the 
desired function(s). 


e The privileged shareable image (or each routine in it) must 
enable any necessary user privileges and disable them when 
they are no longer needed. The Set Privileges (SSETPRV) 
system service is used to enable and disable user privileges. 


Each of the preceding considerations is discussed in the following 
sections. 
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6.1.1 Change-Mode Vector 


One of the program sections in a privileged shareable image must start 
with a change-mode vector. The purpose of this vector is to point (by 
means of self-relative offsets) to the start of the kernel-mode or 
executive-mode dispatch routine within the privileged shareable image. 


The program section containing the change-mode vector must be assigned 
the VEC attribute. (See the VAX-11 MACRO Language Reference Manual or 
the VAX-11 Linker Reference Manual for a discussion of program section 
attributes. ) 





The change-mode vector must have the format shown in Figure 6-1. The 
offsets from the base of the vector to specific items are expressed by 
symbols starting with PLVSL.. These symbols are defined by the 
SPLVDEF macro and are contained in SYSS$LIBRARY:LIB.MLB. 


Vector Type Code 
(PLV$C__TYP__CMOD) PLV$L_TYPE 


System Version Number 
(SYS$K_VERSION) PLV$L__VERSION 





Kernel Mode Dispatcher Offset PLV$L__KERNEL 


Exec Mode Entry Offset PLV$L__EXEC 





Reserved 


Reserved 


RMS Dispatcher Offset PLV$L_.RMS 


Address Check PLV$L__CHECK 








Figure 6-1 Change-Mode Vector Format 


The significant offsets in the change-mode vector and their contents 
are as follows: 


e PLVSL TYPE - Contains the type code PLVSC_TYP_CMOD, 
identifying this as a change-mode vector. 


e PLVSL VERSION - Contains the system version number (expressed 
by the value SYSS$K VERSION). When the privileged shareable 
image is linked, the linker inserts the value of SYSS$K VERSION 
into this location. Before the privileged shareable Image is 
used at run time, the VAX/VMS image activator compares this 
value with the current version number of SYS.EXE; and if the 
two do not match, the privileged shareable image is not used 
and an error status is returned. 


e PLVSL KERNEL - Contains a  self-relative pointer to the 
user-Supplied kernel-mode dispatcher. ("Self-relative" means 
relative to the start of the longword field.) A zero value 
indicates there is no kernel-mode dispatcher. 


e PLVSL_ EXEC ~ Contains a self-relative pointer to the 
user-supplied executive-mode dispatcher. A zero value 
indicates there is no executive-mode dispatcher. 
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e PLVS RMS - Contains a self-relative pointer to the dispatcher 
for VAX-1l1 RMS services. A zero value indicates there is no 
user-supplied VAX-11 RMS dispatcher. Only one privileged 
shareable image should specify the VAX-11 RMS vector, because 
only the last value will be used. This field is intended for 
use only by DIGITAL. 


e PLVSL CHECK ~ Contains a value to verify that a privileged 
shareable image that is not position independent is located at 
the proper virtual address. If the image is position 
independent, this field should contain zero. If the image is 
not position independent, this field should contain its own 
address. 


6.1.2 Entry Point to the Privileged Shareable Image 


The entry point of a privileged shareable image must be an entry mask 
followed by a CHMK (change mode to kernel) or CHME (change mode to 
executive) instruction, depending on whether you want control 
transferred to a kernel-mode or executive-mode dispatcher (specified 
in the vector). The operand of the CHMK or CHME instruction must be a 
negative value, because positive values are _ reserved for calling 
system services supplied by DIGITAL. 


6.1.3 Kernel-Mode or Executive-Mode Dispatcher 
The kernel-mode or executive-mode dispatch code that you write must: 


@e Validate the CHMK or CHME operand, handling any invalid 
operands. 


e Transfer control to the appropriate coding segment if the 
privileged shareable image contains functionally separate 
coding segments. The CASE instruction in VAX-1l1 MACRO or a 
computed GO-TO-type statement in a high-level lanquage 
provides a convenient mechanism for determining where to 
transfer control. 


e Precede the coding segment(s) performing the function(s) the 
privileged shareable image was designed to perform. 


6.1.4 Enabling and Disabling User Privileges 


A privileged shareable image must enable any privileges that it needs 
but that the nonprivileged user of the privileged shareable image 
lacks. The privileged shareable image must also disable any such 
privileges before the nonprivileged user receives control again. 
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To enable or disable a set of privileges, use the Set Privileges 
(SSETPRV) system service. The following example shows the operator 
(OPER) and physical I/O (PHY_10) privileges being enabled. 


PRVMSK: .LONG <1@PRVSV_OPER>!<1@PRVSV_PHY_I0> ;OPER AND PHY IO 
- LONG 0 7QUADWORD MASK REQUIRED. NO BITS SET IN 
7HIGH-ORDER LONGWORD FOR THESE PRIVILEGES, 


SSETPRV_S ENBFLG=#1,- ;l=enable, O=disable 
PRVADR=PRVMSK ;Identifies the privileges 


Any code executing in executive or kernel mode is granted an implicit 
SETPRV privilege. 


The VAX/VMS System Services Reference Manual contains an explanation 
of the Set Privileges (SSETPRV) system service. 





6.2 LINKING THE PRIVILEGED SHAREABLE IMAGE 


The following conventions apply when you link (that is, create) a 
privileged shareable image: 


e Use the /SHAREABLE command qualifier to identify the image to 
be created as shareable. 


e Use the /PROTECT command qualifier or the PROTECT= option to 
identify the entire image or specific clusters, respectively, 
as protected against user-mode or supervisor-mode write access 
(see Section 6.2.1 for further information). 


e Define the privileged shareable image's entry point as a 
universal symbol, using the UNIVERSAL= option. 


The listings in Section 6.5 include the LINK command and linker 
options file used to create the sample privileged shareable image. 


6.2.1 Specifying Protection for the Image or Clusters 


The VAX-11 Linker allows you to protect all or part of a privileged 
shareable image from write access by code executing in user or 
supervisor mode. The /PROTECT command qualifier causes all image 
sections to be so protected. The PROTECT= option in a linker options 
file permits you to specify protection for individual clusters, thus 
allowing privileged shareable images to contain parts into which the 
nonprivileged user can write. 


The linker option takes the form PROTECT=YES or PROTECT=NO = and 
precedes the specifications for clusters that are to be protected or 
unprotected, respectively. The following example shows the _ linker 
options file entries to designate clusters A, B, and D as protected, 
and cluster C as unprotected. 


PROTECT=YES 

CLUSTER=A,,,MODULE1 ,MODULE2 
CLUSTER=B,,,MODULE3,MODULE4,MODULES 
PROTECT=NO 

CLUSTER=C,,,MODULE6 ,MODULE7 
PROTECT=YES 

CLUSTER=D,, ,MODULE8 ,MODULE9 
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The VAX-11 Linker Reference Manual discusses linker options files and 
explains each available option. 


6.3 INSTALLING THE PRIVILEGED SHAREABLE IMAGE 


To make a privileged shareable image usable by nonprivileged programs, 
you must install it as a protected permanent global section. The 
following procedure is recommended: 


l. Move the privileged shareable image to a protected directory, 
such as SYSSSHARE. 


2. Run the INSTALL utility, specifying the /PROTECT, /OPEN, and 
/SHARED qualifiers. You can also specify the 
“HEADER RESIDENT qualifier. The following entry could be 
used to install the privileged shareable image presented in 
Section 6.5 (the image name is USS): 


S$ RUN SYSSSYSTEM: INSTALL 
INSTALL>SYSS$SHARE : USS/PROTECT /OPEN/SHARED/HEADER_RES 


The INSTALL utility is discussed in the VAX/VMS_ System 
Manager's Guide. 


6.4 USING THE PRIVILEGED SHAREABLE IMAGE 


To the nonprivileged user of a privileged shareable image there is no 
difference between using it and using an ordinary shareable image. To 
use a privileged shareable image, the user must: 


e Call the privileged shareable image. 


e Link the privileged shareable image into the executable image 
being created. Note: If the shareable image was installed as 
writeable, you cannot link it into an executable image. You 
must link an uninstalled copy of the writeable shareable image 
into the executable image. 


6.5 PROGRAM LISTINGS 


The rest of this chapter contains listings of modules in a privileged 
shareable image and of a module that calls the privileged shareable 
image. 


USSDISP.LIS 


USER_SYS_DISP 


Table of contents 


(1) 
(1) 
(1) 
(1) 
(1) 
(1) 
(1) 
(1) 


108 
177 
214 
262 
318 
371 
395 
427 
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Declarations and Equates 

Transfer Vector and Service Definitions 
Change Mode Dispatcher Vector Block 
Kernel Mode Dispatcher 

Executive Mode Dispatcher 

Get Time of Day Register Value 

Set Page Fault Cluster Factor 

Null Service 
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0000 1 .TITLE USER SYS DISP - Example of user system service dispatcher 
0000 2 eIDENT /V1.0/ — 

0000 3; 

0000 4 ; Copyright (C) 1980 

0000 5 ; Digital Equipment Corporation, Maynard, Massachusetts 01754 

0000 6; 

0000 7 ; This software is furnished under a license for use only on a single 
0000 8 ; computer system and may be copied only with the inclusion of the 
0000 9 ; above copyright notice. This software, or any other copies thereof, 
0000 10 ; may not be provided or otherwise made available to any other person 
0000 11; except for use on such system and to one who agree to these license 
0000 12 ; terms. Title to and ownership of the software shall at all times 
0000 13 ; remain in DEC. 

0000 14; 

0000 15 ; The information in the software is subject to change without notice 
0000 16 ; and should not be construed as a commitment by Digital Equipment 
0000 17 7 Corporation. 

0000 18 ; 

0000 19 ; DEC assumes no responsibility for the use or reliability of its 
0000 20 ; software on equipment which is not supplied by DEC. 

0000 21; 

0000 22 ; 

0000 23; Facility: Example of User Written System Services 

0000 24 344+ 

0000 25 ; Abstract: 

0000 26 ; This module contains an example dispatcher for user written 
0000 27 3 system services along with several sample services. It is a 
0000 28 ; template intend to serve as the starting point for implementing 
0000 29 ; a privileged shareable image containing your own services. When used as 
0000 30 ; a template, the definitions and code for the sample services 


0000 31 should be removed. 
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ooo00 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
oco0 
0000 
0000 
0000 
0c00 
0000 
0000 
0000 
0000 
0000 
0000 
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0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
co00 
0000 
0000 
oo0G 
0000 
0000 
0000 


of 


32 ; 
33 ; Overview: 
34 ; User written system services are contained in privileged shareable 
35 ; images that are linked into user program images in exactly the 
BHF same fashion as any shareable image. The creation and installation 
ao 3 of a privileged, shareable image is slightly different from that 
38 ; of an ordinary shareable image. These differences are: 
39 ; 
40 ; 1. A vector defining the entry points and providing other 
4l ; control information to the image activator. This vector 
42 ; is a the lowest address in an image section with the VEC 
43; attribute. 
44 ; 
45 ; 2. The shareable image is linked with the /PROTECT option 
46; that marks all of the image sections so that they will 
47 ; protected and given EXEC mode ownership by the image 
48 ; activator. 
49 ; 
503.33 3. The shareable image MUST be installed /SHARE /PROTECT 
Sly with the INSTALL utility in order for the image activator 
52s to connect the privileged shareable image to the change mode 
53; dispatchers. 
54; 
553 A privileged shareable image implementing user written system services is 
56 ; comprised of the following major components: 
57 3; 
user system service dispatc 10-MAR-1980 15:48:30 VAX-11 Macro V02.42 Page 2 
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58 ; 1. A transfer vector containing all of the entry points and 
59-3 collecting them at the lowest virtual address in the shareable 
60 ; image. This formalism enables revision of the shareable 
61; image without necessitating the relinking of images that 
62 37 use it. 
63 ; 
64; 2. A Privileged Library Vector in a PSECT with the VEC attribute 
65 3 that describes the entry points for dispatching EXEC and 
66 ; KERNEL mode services along with validation information. 
67 3 
68 ; 3. A dispatcher for kernel mode services. This code will 
69.3 be called by the VMS change mode dispatcher when it 
7O ; fails to recognize a kernel mode service request. 
71; 
72; 4, A dispatcher for executive mode services. This code will 
733 be called by the VMS change mode dispatcher when it fails 
74; to recognize an executive mode service request. 
ES. & 
76 ; 5. Service routines to perform the various services. 
? 


77 
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oo0ce 183 The first four components are contained in this template and are 
0000 79; most easily implemented in MACRO, while the service routines can 
0000 80 ; be implemented in BLISS or MACRO. Other languages may be usable 
0000 81; but are not recommended -~ particularly if they require runtime 
0000 82 ; support routines or are extravagant in their use of stack or are 
0000 83; unable to generate PIC code. 
0000 84 ; 
0000 85 ; This example is position-independent (PIC) and it is good practice 
0000 86 ; to implement shareable images this way whenever possible. 
0000 87 4¢s> 
0000 88 ; 
0000 89 ; Link Command File Example: 
0000 90 ; 
0000 91 ; $! 
0000 92; $! Command file to link User System Service example. 
0000 93; $! 
0000 94 ; S LINK/PROTECT /NOSYSSHR/SHARE=USS/MAP=USS/FULL SYSSINPUT/OPTIONS 
0000 95-3 ! 
0000 96 ; ! Options file for the link of User System Service example. 
0000 97 3 ! 
0000 98 ; SYSSSYSTEM:SYS.STB/SELECTIVE 
0000 99 ; £ 
0000 100 ; ! Create a separate cluster for the transfer vector. 
Q000 101 ; ! 
0000 102 ; CLUSTER=TRANSTER_VECTOR,,,SYSSDISK: {] USSDISP 
0000 103 ; U 
0000 104 ; GSMATCH=LEQUAL ,1,1 
0000 105 ; 
0000 106 ;-- 
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v1.0 Declarations and Equates 10-MAR-1980 15:48:21 _DBB2: [HUSTVEDT. USS] USSDISP .-MAR; 23 (1) 
0000 108 ~SBTTL Declarations and Equates 
0000 109 ; 
0000 110 ; Include Files 
0000 she Be Se 3 
0000 112 
0000 113 » LIBRARY "SYSSLIBRARY:LIB.MLB" ; Macro library for system structure 
0000 114 ; definitions 
6000 LVS; 
0000 116 ; Macro Definitions 
0000 117 ; 
0000 LES 3 DEFINE SERV$CE - A macro to make the appropriate entries in several 
0000 119 ; = different PSECTs required to define an EXEC or KERNEL 
0000 120 ; mode service. These include the transfer vector, 
0000 121 ; the case table for dispatching, and a table containing 
0000 122 ; the number of required arguments. 
0000 123 ; 
0000 124 ; DEFINE SERVICE Name,Number_ of Arguments,Mode 
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0co00000 


0000 
oc00 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
ocoo 
0000 
90000 
0000 
0000 
0000 
0000 
0000 


125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
i151 
152 
153 
154 
155 
156 
157 
158 
139 
160 
161 
162 
163 
164 


a 


sete 


Tne Nee 


»«MACRO DEFINE SERVICE,NAME ,NARG=0 ,MODE=KERNEL 

.PSECT $SSTRANSFER VECTOR, PAGE,NOWRT,EXE,PIC 

-ALIGN QUAD =e ; Align entry points for speed and style 
«TRANSFER NAME ; Define name as universal symbol for entry 
-MASK NAME ; Use entry mask defined in main routine 


bE IDN MODE,KERNEL 
CHMK #<KCODE_BASE+KERNEL COUNTER> ; Change to kernel mode and execute 
RET ; Return 


2 
KERNEL COUNTER=KERNEL COUNTER+1 3; Advance counter 


»PSECT KERNEL NARG ,BYTE,NOWRT,EXE,PIC 
~ BYTE NARG ; Define number of required arguments 


-PSECT USER_KERNEL DISP1,BYTE,NOWRT,EXE, PIC 


«WORD 2+NAME-KCASE_BASE ; Make entry in kernel mode CASE table 
~IFF 

CHME #<ECODE BASE+EXEC_COUNTER> ; Change to executive mode and execute 
RET ; Return 

EXEC_COUNTER=EXEC_COUNTER+1 ; Advance counter 


~PSECT EXEC_NARG ,BYTE,NOWRT,EXE, PIC 
»~BYTE NARG ; Define number of required arguments 


-PSECT USER EXEC_DISP1,BYTE,NOWRT,EXE, PIC 

- WORD 2+NAME-ECASE_BASE Make entry in exec mode CASE table 
~ENDC 

«ENDM DEFINE SERVICE 


Equated Symbols 


SPHDDEF ; Define process header offsets 
SPLVDEF ; Define PLV offsets and values 
SPRDEF ; Define processor register numbers 


Initialize counters for change mode dispatching codes 


ERNEL COUNTER=0 3 Kernel code counter 


SGOWWI ATAVGUYVHS GaOTTIAIYd 
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Declarations and Equates 


00000000 0000 
0000 
0000 
0000 
0000 

00000000 
0000 
0000 

00000000 
0000 
0000 
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165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
i775: 


EXEC_COUNTER=0 


Own Stor 


Me te se 


-PSECT 
KERNEL_NARG: 


~PSECT 
EXEC_NARG: 


Transfer Vector and Service Defi 


0000 
9000 
0000 
9000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
00006 
0002 
0002 
0004 
0004 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 


0002 
0002 
FFFFFCOO 0002 
FFFFFCOO 0002 


177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 


209 
210 
211 
212 


~SBTTL 

ptt 

; 

i 

i 

? 

; 

; 

7 

i 

? 

7 Shareable imag 

, 

3-- 
DEFINE _S 
DEFINE_S 
DEFINE S 

; 

; 

; 

i 

; 

7 mode instructi 

; 

7 

7 


7 particular service routine determines 


7 
KCODE_BASE=-1024 
RCODE BASE=~-1024 
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3; Exec code counter 


age 


KERNEL NARG ,BYTE,NOWRT,EXE,PIC 
a ; Base of 
? number 
EXEC_NARG ,BYTE,NOWRT,EXE, PIC 
; Base of 
7 number 


byte table containing the 
of required arguments. 


byte table containing the 
of required arguments. 
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Transfer Vector and Service Definitions 


e must not change so some padding 


the opportunity for future growth. 


ERVICE USER _GET_TODR,1,KERNEL 


ERVICE USER SET PFC,2,KERNEL 


mee me se 


ERVICE USER_NULL,0,EXEC 


The use of transfer vectors to effect entry to the user written system services 
enables some updatina of the shareable image containing them without necessitating 
a re-link of all programs that call them. The PSECT containinng the transfer 
vector will be positioned at the lowest virtual address in the shareable image 
and so lona as the transfer vector is not re-ordered, programs linked with 


one version of the shareable image will continue to work with the next. 


Thus as additional services are added to a privileged shareable image, their 
definitions should be added to the end of the following list to ensure that 
programs using previous versions of it will not need to be re-linked. 

To completely avoid relinking existing programs 


the size of the privileged 
will be required to provide 


Service to get value of time 
of day register 

Service to set value of process 
default pagefault cluster 

Null exec service 


The base values used to generate the dispatching codes should be negative for 
user services and must be chosen to avoid overlap with any other privileged 

shareable images that will be used concurrently. 
deferred to this point in the assembly to cause their use in the preceding 
macro calls to be forward references that guarantee the size of the change 


Their definition is 


ons to be four bytes. This satisfies an assumption that is 


made by for services that have to wait and be retried. The PC for retrying 
the change mode instruction that invokes the service is assumed to be 4 bytes 
less than that saved in the change mode exception frame. Of course, the 


whether this is possible. 


; Base CHMK code value for these services 
; Base CHME code value for these services 
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0002 214 -SBTTL Change Mode Dispatcher Vector Block 
0002 215 t+ 
0002 216 ; This vector is used by the image activator to connect the privileged shareable 
0002 217 ; image to the VMS change mode dispatcher. The offsets in the vector are self- 
0002 218 ; relative to enable the construction of position independent images. The system 
0002 219 ; version number will be used by the image activator to verify that this shareable 
0002 220 ; image was linked with the symbol table for the current system. 
0002 221 3 
0002 222 % Change Mode Vector Format 
0002 223 ; 
0002 224 ; $----------------------~+----------+------- + 
0002 225 ; ! Vector Type Code ! PLVSL_TYPE 
0002 2269 ! (PLVSC TYP CMOD) ! 
0002 227 ; Henna =---=------------------ + 
0002 228 ; ! System Version Number i PLVSL_VERSION 
0002 229 ; ! (SYSSK_VERSION) ! 
0002 230 ; +------------ = + 
0002 231 ; ! Kernel Mode Dispatcher Offset ! PLVSL_KERNEL 
0002 232.2 ! i 
0002 233; $o-------------- ----- -- = = $= = == === == + 
0002 234 ; ! Exec Mode Entry Offset ! PLVSL_EXEC 
0002 235. 7 ! ! 
0002 236 ; 4---------- ~~ - 5 ~~~ ern + 
0002 237 ; ! Reserved ! 
0002 238 ; ! ! 
0002 239 ; $n en eo ne nn + 
0002 240 ; ! Reserved ! 
0002 241 ; ! ! 
0002 242 ; ha ee rr r= + 
0002 2435 ! RMS Dispatcher Offset ! PLVS$L_RMS 
0002 244 ; ! ! 
0002 245 ; $n ee rns + 
0002 246 ; ! Address Check ! PLVSL_CHECK 
0002 247 3; ! ! 
0002 248 ; too 22-2 $e = + 
0002 249 ; 
0002 250 ; 
00000000 251 +PSECT USER_SERVICES, PAGE,VEC,PIC,NOWRT,EXE 
0000 252 
oo00coo1l 0000 253 ~ LONG PLVSC TYP CMOD ; Set type of vector to change mode 
pane ; dispatcher 
oooocooo' 0004 254 . LONG SYSS$K VERSION ; Identify system version 
00000005° 0008 255 - LONG KERNEL DISPATCH-. 3 Offset to kernel mode dispatcher 
00000001' o00DC 256 - LONG EXEC DISPATCH-. 3; Offset to executive mode dispatcher 
ooo00000 0010 257 -LONG O 7 ; Reserved. 
00000000 0014 258 - LONG 0 ; Reserved. 
00000000 0018 259 «LONG 0 7 No RMS dispatcher 
00000000 o01c 260 «LONG 0 ; Address check - PIC image 
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50 


50 


51 


51 


0000'S8F 


OO00'SF 


c400 co 
F8 
02 51 
F3 


OOOO0'CF41 


51 00000004 9F41 


0400'CF40 6C 


ol 


D1 
50 


FCOO 8F 
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~SBTTL 
ptt 


(SP) - 
RO - 


Ra - 


AP = 


FP - 


Nee ee se Se ee Me ee ee Se ee te 


KACCVIO: 
MOVZWL 
RET 

KINSFARG: 
MOVZWL 
RET 

KNOTME: RSB 


KERNEL DISPATCH: : 


MOVAB 
BLSS 
CMPW 
BGEQU 


The dispatch 


verified. 


Ne tee ee 


MOVZBL 
MOVAL 
TFNORD 
CMPB 
BLSSU 
CASEW 


KCASE_BASE: 


we Ne Se se we 


-PSECT 
RSB 


Change Mode Dispatcher 
0020 262 
0020 263 
0020 264 
0020 265 
0020 266 
0020 267 
0020 268 
0020 269 
0020 270 
0020 271 
0020 272 
0020 273 
0020 274 
0020 275 
0020 276 
0020 277 
0020 278 
0020 279 

00000000 280 
0000 281 
3c 0000 282 
04 0005 283 
0006 284 
3c 60006 285 
04 000B 284 
05 oo0nc 287 
onoD 288 
oo00D 289 
9E O000D 290 
19 0012 291 
Bl 90014 292 
1lE 0017 293 
0019 294 
0019 295 
0019 296 
0019 297 
0019 298 
9A 0019 299 
DE OO1F 300 
0027 301 
91 002D 302 
1F 0033 303 
AF 0035 304 
0037 305 
0037 304 
0037 307 
003B 308 
0038 309 
003B 310 
003B 311 
003B 312 
003B 313 
900000000 314 
05 0000 315 
0001 3146 
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Kernel Mode Dispatcher 


Input Parameters: 


Return address if bad change mode value 
Chanee mode argument value. 


Current PCR Address. (Therefore R4 must be specified in all 
register save masks for kernel routines.) 


Argument pointer existing when the change 
mode instruction was executed. 


Address of minimal call frame to exit 
the change mode dispatcher and return to 
the original mode. 


USER KERNEL DISPO,BYTE,NOWRT,EXE,PIC 

~ = Kernel access violation 

Set access violation status code 
and return 

Kernel insufficient arguments. 

Set status code and 
return 

RSB to forward request 


#SSE_ACCVIO,RO 


#SSS_INSFARG ,RO 


See ee Se See 


Entry to dispatcher 


W°-KCODE_BASE (RO) ,R1 Normalize dispatch code value 


me Ne ee Se 


KNOTME Branch if code value too low 
R1,#KERNEL COUNTER Check high limit 
KNOTME Branch if out of range 


code has now been verified as being handled by this dispatcher, 


now the argument list will be prohed and the required number of arguments 


W°KERNEL NARG[R1],R1 7 Get required argument count 
@#4[R1],R1 ; Compute byte count including arg count 
Rl, (AP) ,KACCVIO ; Branch if arglist not readable 


(AP) ,W°<KERNEL NARG-KCODE BASE>[RO] ; Check for required number 
KINSFARG ~ ~ of arguments 

RO,- Case on change mode 

- argument value 

#KCODE BASE,-— Base value 

#<KERNEL COUNTER-1> Limit value (number of entries) 

~ Case table base address for DEFINE SERVICE 


we Se Ne se te Se 


Case table entries are made in the PSECT USER_KERNEL DISP1 by 
invocations of the DEFINE SERVICE macro. The three PSECTS, 
USER_KERNEL DISPO,1,2 will be abutted in lexical order at link-time. 


USER_KERNEL_DISP2,BYTE,NOWRT,EXE, PIC 
; Return to reject out of 
; range value 
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v1.0 Executive Mode Dispatcher 10-MAR-1980 15:48:21 | DBB2: [HUSTVEDT.USS] USSDISP.MAR; 23 (1) 
0001 318 ~SBTTL Executive Mode Dispatcher 
oool 319 34++ 
0001 320 ; Input Parameters: 
0001 3213 
0001 322 ; (SP) - Return address if bad change mode value 
o0o1 323 ; 
0001 324 ; RO -~- Change mode argument value. 
0001 32573 
0001 326 ; AP - Argument pointer existing when the change 
0001 327 mode instruction was executed. 
0001 328 ; 
0001 329 ; FP - Address of minimal call frame to exit 
0001 330 ; the change mode dispatcher and return to 
0001 331 ; the original mode. 
0001 3320 ¢=- 
00000000 333 »-PSECT USER EXEC DISPO,BYTE,NOWRT,EXE,PIC 
0000 334 EACCVIO: = = ; Exec access violation 
50 0000'8F 3c 60000 335 MOVZWL #SS$ ACCVIO,RO ; Set access violation status code 
04 0005 336 RET = ; and return 
0006 337 EINSFARG: 7 Exec insufficient arguments. 
50 0000'8F 3C 0006 338 MOVZWL #SSS_INSFARG,RO ; Set status code and 
04 000B 339 RET a 7 return 
05 o00Cc 340 ENOTME: RSB ? RSB to forward request 
000D 341 
000D 342 EXEC DISPATCH:: 7 Entry to dispatcher 
51 0400 co 9E 0O00D 343 a MOVAB W°-ECODE BASF (RO) ,R1 3 Normalize dispatch code value 
F8 19 0012 344 BLSS ENOTME — ; Branch if code value too low 
ol 51 Bl 0014 345 CMPW Rl,#EXEC COUNTER 3 Check high limit 
F3 1E 0017 346 BGEQU ENOTME — 3; Branch if out of range 
0019 347 ; 
0019 348 ; The dispatch code has now been verified as being handled by this dispatcher, 
0019 349 ; now the argument list will be probed and the required number of arguments 
0019 350 ; verified. 
0019 351; 
51 0000'CF41 9A 0019 352 MOVZBL W°EXEC_NARG[R1],R1 ; Get required argument count 
51 00000004 9F41 DE O0O1F 353 MOVAL @#4[R1],R1 ; Compute byte count including arg count 
0027 354 IFNORD R1, (AP) ,EACCVIO ; Branch if arglist not readable 
0400'CF40 6c 91 002D 355 CMPB (AP) ,W°<EXEC NARG-ECODE BASE>[RO] ; Check for required number 
Dl 1F 0033 356 BLSSU  _ EINSFARG 7 “; of arguments 
50 AF 0035 357 CASEW RO,- 7 Case on change mode 
0037 358 - 7 argument value 
0037 359 #ECODE BASE,- ; Base value 
00 FCOO 8F 0037 360 #<EXEC COUNTER-1> ; Limit value (number of entries) 
003B 361 ECASE BASE: a 7 Case table base address for DEFINE SERVICE 
003B 362; 
003B 363 ; Case table entries are made in the PSECT USER EXEC DISP1 by 
003B 364 ; invocations of the DEFINE SERVICE macro. The three PSECTS, 
003B 365 ; USER_EXEC_DISP0,1,2 will be abutted in lexical order at link-time. 
003B 366 ; 
oo000000 367 -PSECT USER EXEC DISP2,BYTE,NOWRT,EXE,PIC 
05 0000 368 RSB = ie ; Return to reject out of 
0001 369 3} range value 
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v1.0 Get Time of Day Register Value 1O-MAR-1980 15:48:21 _DBB2: (HUSTVEDT.USS] USSDISP .MAR; 23 (1) 
0001 371 -SBTTL Get Time of Day Register Value 
0001 372 p++ 
0001 373 ; Functional Description: 
0001 374 ; This routine reads the content of the hardware time of day 
0001 375 ; processor register and stores the resulting value at the 
0001 376 ; specified address. 
0001 377 ; 
0001 378 ; Input Parameters: 
0001 379 ; O4(AP) - Address to return time of day value 
oool 380 ; R4 ~ Address of current PCB 
0001 381 ; 
0001 382 ; Output Parameters: 
0001 383 ; RQ - Completion Status Code 
0001 384 ;-- 
001c 0001 385 »~ENTRY USER GET TODR, “M¢<R2,R3,R4> 
51 04 AC DO 60003 386 MOVL 4(AP),R1~ ; Get address to store time of day register 
0007 387 IFNOWRT #4, (R1),10S ; Branch if not writable 
61 1B DB OOOD 388 MFPR #PRS TODR, (R1) ; Return current time of day register 
50 oooc00000' SF DO 0010 389 MOVL #SSS” NORMAL ,RO 7 Set normal completion status 
04 0017 390 RET ~ ; and return 
0018 391 
50 o0oo00'sF 3c 600018 392 108: MOVZWL #SS$ ACCVIO,RO ; Indicate access violation 
04 #OOlD 393 RET 2 ; 
USER_SYS_DISP - Example of user system service dispatc 10-MAR-1980 15:48:30 VAX-11 Macro V02.42 Page 10 
v1.0 Set Page Fault Cluster Factor 10-MAR-1980 15:48:21 _DBB2: {HUSTVEDT.USS] USSDISP .MAR; 23 (1) 
OO1E 395 -SBTTL Set Page Fault Cluster Factor 
OO1E 396 ;++ 
OOLE 397 ; Functional Description: 
OO1E 398 ; This routine sets the page fault cluster to the specified value 
OOLE 399 ; and returns the previous value. 
OOLE 400 ; 
OOlE 401 ; Input Parameters: 
OO1E 402 ; O4(AP) - New value for Page Fault Cluster factor 
OO1E 403 ; O8(AP) - Address to return previous value 
OO1E 404 ; (0 means none) 
OOlE 405 ; R4 - PCB address of current process 
OO1LE 406 ; 
OO1E 407 ; Output Parameters: 
OO1E 408 ; RO —- Completion Status code 
OO1E 409 ;-- 
0030 OO1E 410 ~ENTRY USER SET PFC, *M<R4,R5> 
55 coooc00c'o9F po 0020 411 MOVL @#CTLSGL_PHD,R5 ; Get address of process header 
51 08 Ac DO 0027 412 MOVL 8(AP),R1 } Get address to store previous value 
0A 13 0028 413 BEQL 10$ 7 Branch if none 
002D 414 IFNOWRT #4,(R1),30S ; Branch if not writable 
61 34 AS 9A 0033 415 MOVZ2BL PHDSB DFPFC(R5),(R1) ; Return current value 
7P 8F 04 AC 91 0037 416 10S: CMPB 4 (AP), #127 ; Check for legal value 
04 1B 003C 417 BLEQU 20$ ; Branch if legal 
50 7F 8F 90 O03E 418 MOVB #127,R0 7 Set to maximum value 
34 AS 50 90 0042 419 208: MOVB RO,PHDSB DFPFC(R5) ; Set new value into PHD 
50 00000000'8F DO 0046 420 MOVL #SSS NORMAL ,RO ; Set normal completion status 
04 OC4D 421 RET 7 + and return 
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USER SYS DISP 
v1.0 


0000'8F 


0000'8F-. 


3c 
04 


OO4E 
OO4E 
0053 
0054 


422 

423 308: MOVZWL #SSS_ACCVIO,RO 
424 RET 

425 


- Example of user system service dispatc 10-MAR-1980 15: 


Null Service 


0co0 
3c 
04 


0054 
0054 
0054 
0054 
0054 
0054 
0054 
0054 
0054 
0054 
0054 
0056 
005B 
005c 
00sC 


427 
428 
429 
430 
431 
432 
433 
434 
435 
436 
437 
438 
439 
440 
44] 


10-MAR-1980 


-SBTTL Null Service 
pak 
3 Functional Description: 
7 
7; Input Parameters: 
z 
7 Output Parameters: 
7 
-- 
- ENTRY USER_NULL, “M<> 
MOV ZWL #SSS_ NORMAL ,RO 
RET 
- END 


15: 


; Indicate access violation 
i 


48:30 VAX-11 Macro V02.42 Page 11 
48:21 _DBB2: (HUSTVEDT.USS] USSDISP .MAR; 23 (1) 


7 Entry definition 
3; Set normal completion status 
7 and return 
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USER_SYS_DISP 
Symbol table 


BIT... = 
CTLSGL_PHD 
EACCVIO 

ECASE BASE 
ECODE_BASE = 
EINSFARG 

ENOTME 
EXEC_COUNTER = 
EXEC DISPATCH 
EXEC NARG 
GBL... 

KACCVILO 

KCASE BASE 
KCODE_BASE = 
KERNEL COUNTER = 
KERNEL DISPATCH 
KERNEL NARG 
KINSFARG 

KNOTME 
PHDSB_ASTLVL 
PHDSB_CPUMODE 
PHDSB_DFPFC 
PHDSB PAGFIL 
PHDSB_PGTBPFC 
PHDSC_LENGTH 
PHD$C_PHDPAGCTX= 
PHDS$K_LENGTH 
PHDSL BIOCNT 
PHDSL_CPULIM 
PHDSL_ CPUTIM 
PHD$L_DIOCNT 
PHDS$L_ESP 
PHDSL_FREPOVA 
PHDS$L_FREP1VA 
PHD$L_PREPTECNT 
PHDSL_IMGCNT 
PHDSL_KSP 
PHDSL_POBR 
PHDSL_POLRASTL 
PHD$L_ P1BR 
PHDSL_P1LR 

PHDSL PAGEFLTS 
PHDSL_ PAGFIL 
PHDSL_PC 

PHDS$L_ PCB 

PHD$L PFLREF 
PHD$L_PFLTRATE 
PHD$L_ PGFLTIO 
PHDS$L” PSL 
PHDSL_PSTBASOFF 
PHDSL_ PTWSLELCK 
PHDSL_ PTWSLEVAL 
PHDS$L_RO 
PHDSL_R1 
PHDSL_R10 

PHDSL R11 
PHDS$L_R12 


0cooo0co 
RRR KK 
00000000 
0000003B 
FFFFFCOO 
00000006 
0000000Cc 
00000001 
a000000D 
00000000 


= 00000000 


00000000 
0000003B 
FFFFFCOO 
00000002 
0000000D 
00000000 
00000006 
o0000000C 
000000CB 
o0o000005C 
00000034 
QO000001F 
00000035 
00000180 
00000008 
00000180 
00000054 
00000058 
00000038 


am 


RG 


R 
R 
R 


00000050. 


00000078 
00000028 
60000030 
0000c002C 
O00000F4 
00000074 
oooo00c4 
000000C8 
000000CC 
o00000D0 
00000048 
o0000001Cc 
000000BC 
00000074 
oo00000FC 
OOO0000F8 
o000004Cc 
o00000c0 
00000020 
00000060 
00000064 
00000084 
00000088 
0O0000AC 
000000B0 
00000034 
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oc 
0B 
OB 


OB 
OB 


OB 
04 


09 
09 


09 
03 
09 
09 


PHDSL_R13 
PHDSL_ R2 
PHDSL_R3 
PHDSL_ R4 
PHDSL_RS5 

PHDSL_ RA 
PHDSL_R7 
PHDSL_ R8 
PHDSL RQ 
PHDS$L_REFERFLT 
PHDSL RESLSTH 
PHDSL SPARE 
PHDSL SSP 
PHDSL TIMREF 
PHDSL_ USP 
PHD$L WSL 
PHD$M_DALCSTX 
PHDSM PFMFLG 
PHD$M_ WSPEAKCHK 
PHDSQ AUTHPRIV 
PHDS$Q IMAGPRIV 
PHD$Q PRIVMSK 
PHDS$S ASTLVL 
PHDSS POLR 
PHDSV_ASTLVL 
PHDSV_DALCSTX 
PHD$V POLR 
PHDSV_PFMFLG 
PHDSV_WSPEAKCHK 
PHDSW ASTLM 
PHDSW BAK 
PHDSW CWSLX 
PHDSW DFWSCNT 
PHDSW_ EMPTPG 
PHDSW_EXTDYNWS 
PHDSW FLAGS 
PHDSW PHVINDEX 
PHDSW PRCLM 
PHDSW PST 
PHDSW PSTBASMAX 
PHDSW PSTFREE 
PHDSW PSTLAST 
PHDSW PTCNTACT 
PHDSW PTCNTLCK 
PHD$W_PTCNTMAX 
PHDSW PTCNTVAL 
PHDSW QUANT 
PHDSW REQPGCNT 
PHDSW RESPGCNT 
PHDSW WSAUTH 
PHD$W WSDYN 
PHDSW WSFLUID 
PHDSW WSLAST 
PHDSW WSLIST 
PHDSW WSLOCK 
PHDSW WSLX 
PHDSW_WSNEXT 


000000B8 
0000008C 
00000090 
00000094 
00000098 
ooo0009c 
OO00000A0 
O00000A4 
O00000A8 
00000014 
O00000F0 
0000013C 
0000007C 
00000100 
00900080 
00000180 
00000002 
00000001 
00000004 
ooo000pc 
OO0000E4 
00000000 
00000008 
00000018 
00000018 
00000001 
00000000 
00000000 
00000002 
00000040 
00000044 
OO00000DA 
OOO00001A 
o00000D4 
00000072 
00000036 
00000042 
0000003E 
00000020 
00000046 
00000026 
00000024 
o000006Cc 
00000068 
OO0OO00KE 
OO000006A 
0000003C 
ooo000Ds 
000000D6 
O0CO000A 
COOOODODE 
00000070 
00000012 
00000008 
oo000000c 
00000046 
00000010 
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PHDS$W WSQUOTA 
PLVSC_TYP_CMOD 
PLVSC_TYP MSG 
PLVSL CHECK 
PLVSL EXEC 
PLVSL KERNEL 
PLVSL MSGDSP 
PLVSL RMS 
PLVSL_TYPE 
PLVSL_ VERSION 
PR$S_SID_ECO 
PRS$S SID PL 
PRSS SID SN 
PRSS_SID_TYPE 
PRSV_SID_ECO 
PRSV_ SID PL 
PRSV_SID_SN 
PRSV_SID_TYPE 
PR$ ACCR 
PRS$_ACCS 

PRS ASTLVL 
PRS_CADR 

PRS CAER 

PRS CMIERR 
PRS CSRD 

PRS CSRS 
PRS_CSTD 

PRS _CSTS 
PRS_ESP 

PRS ICCS 

PRS ICR 

PRS” IPL 

PRS ISP 

PRS KSP 
PRS_MAPEN 

PRS MCESR 

PRS$ NICR 

PRS” POBR 

PRS POLR 

PRS P1BR 

PRS P1LR 

PRS PCBB 

PRS PME 

PRS RXCS 

PRS RXDB 

PRS SBIER 

PRS SBIFS 

PR$ SBIMT 

PRS SBIOC 
PRS_SBIS 

PRS SBISC 

PRS SBITA 
PRS_SBR 

PRS SCBB 

PRS SID 
PRS$_SID_TYP750 
PRS_SID_TYP780 
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00000018 
00000001 
00000002 
oo0000dic 
o000000C 
00000008 
00000008 
00000018 
00000000 
00000004 
00000008 
00000004 
o000000c 
00000008 
00000010 
0000000C 
00000000 
00000018 
00000029 
00000028 
00000013 
00000025 
00000027 
00000017 
0000001D 
o000001Cc 
OO0O00001F 
OOOO001E 
00000001 
00000018 
OOOOCO001A 
00000012 
00000004 
00000000 
00000038 
00000026 
00000019 
00000008 
00000009 
OO00000A 
0000000B 
90000010 
0000003D 
00000020 
00000021 
00000034 
00000030 
00000033 
00000036 
00000031 
00000032 
00000035 
0000000C 
00000011 
0000003E 
00000002 
00000001 
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Symbol table 10-MAR-1980 15:48:21 _DBB2: [HUSTVEDT.USS]USSDISP .MAR; 23(1) 
PR$ SID TYP7ZZ = 00000003 
PRS” SID _TYPMAX = 00000003 
PRS SIRR = 00000014 
PRS SISR = 00000015 
PRS_SLR = 0000000D 
PR$_SSP = 90000002 
PRS TBDR = 00000024 
PRS TBIA = 00000039 
PR$_TBIS = 0000003A 
PR$_TODR = 0000001B 
PRS$_TXCS = 00000022 
PR$”TXDB = 00000023 
PR$_UBRESET = 00000037 
PRS$_USP = 00000003 
PRS _WCSA = 0000002c 
PR$_WCSD = 0000002D 
SsS$_ACCVIO RRRKERER XQ 
SS$_INSFARG RRERERER X09 
SS$” NORMAL RREKKKRE  X OC 
SYSS$K_VERSION RRAKKKKR X 08 
USER GET TODR 00000001 RG oc 
USER NULL 00000054 RG oc 
USER_SET_PFC 0000001E RG oc 
4+---------------- + 
! Psect synopsis ! 
pee a ea a ee ee ee 
PSECT name Allocation PSECT No. Attributes 
- ABS . 00000000 ¢ 0.) OO ( O.) NOPIC USR CON ABS LCL NOSHR NOEXE NORD NOWRT NOVEC BYTE 
- BLANK . oooo00co $ ¢ 0.) O1 ( 1.) NOPIC USR CON REL LCL NOSHR EXE RD WRT NOVEC BYTE 
SABSS$ 00000184 ( 388.) 02 ( 2.) NOPIC USR CON ABS LCL NOSHR EXE RD WRT NOVEC BYTE 
KERNEL_NARG ooo00002 2.) 03 ( 3.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
EXEC_NARG ooo00001 ¢ 1.) 04 ( 4.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
$$$TRANSFER_VECTOR 00000017 ¢ 23.) 05 ( 5.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC PAGE 
USER_KERNEL DISP1 ooo00004 4.) 06 ( 6.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER_EXEC_DISP1 oo00c002 ¢ 2.) O07 ( 7.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER_SERVICES 00000020 ( 32.) 08 ( 8.) PIC USR CON REL LCL NOSHR EXE RD NOWRT VEC PAGE 
USER KERNEL DISPO 0000003B ( 59.) 09 ( 9.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER_KERNEL_DISP2 ooo000001 ¢ 1.) OA ( 10.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER_EXEC_DTSPO 0000003B ( 59.) OB ( 11.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER_EXEC_DISP2 oooo005c ( 92.) ac ( 12.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
+------------------------ + 
! Performance indicators ! 
4+------ + 
Phase Page faults CPU Time Elapsed Time 
Initialization 8 00:00:00.04 00:00:00.18 
Command processing 13 00:00:00.18 00:00:00.46 
Pass 1 306 00:00:06.64 00:00:09.97 
Symbol table sort 7 00:00:00.25 00:00:00.41 
Pass 2 200 00:00:01.49 00:00:02.00 
Symbol table output 27 00:00:00.12 00:00:00.15 


Psect synopsis output 5 00:00:00.06 00:00:00,06 
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VAX-1] Macro Run Statistics 10-MAR-1980 15:48:21 
Cross-reference output 6 00:00:00.00 00:00:00.00 
Assembler run totals 567 00:00:08.78 00:00:13.24 


The working set limit was 293 pages. 

27596 bytes (54 pages) of virtual memory were used to buffer the intermediate code. 

There were 10 pages of symbol table space allocated to hold 194 non-local and 4 local symbols. 
441 source lines were read in Pass 1, producing 41 object records in Pass 2. 

17 pages of virtual memory were used to define 15 macros. 


+-------------------------- + 
! Macro library statistics ! 
tanec nn ne = + 

Macro library name Macros defined 

_DRAS: (SYSLIB]LIB.MLB;1 14 

_DRAS: (SYSLIB]STARLET.MLB;1 0) 

TOTALS (all libraries) 14 


427 GETS were required to define 14 macros. 
There were no errors, warnings or information messages. 


USSDISP/LIS 
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USSTEST 10-MAR-1980 15:12:23 VAX-11 Macro V02.42 Page 0 
Table of contents 


(1) 45 Sample invocation of user written system 
USSTEST 10-MAR-1980 15:12:23 VAX-11 Macro V02.42 Page Hk 
v1.0 10-MAR-1980 15:02:56 —DBB2:[HUSTVEDT.USS] USSTEST.MAR;5 (1) 
0000 1 «TITLE USSTEST 
0000 2 -IDENT /V1.0/ 
0000 Bice 
0000 4 ; Copyright (C) 1980 
0000 5 ; Digital Equipment Corporation, Maynard, Massachusetts 01754 
0000 GF 
0000 7 ; This software is furnished under a license for use only on a single 
0000 8 ; computer system and may be copied only with the inclusion of the 
0000 9 ; above copyright notice. This software, or any other copies thereof, 
0000 10 ; may not be provided or otherwise made available to any other person 
0000 ll ; except for use on such system and to one who agree to these license 
0000 12 ; terms. Title to and ownership of the software shall at all times 
0000 13; remain in DEC. 
0000 14 ; 
0000 15 ; The information in the software is subject to change without notice 
0000 16 ; and should not be construed as a commitment by Digital Equipment 
0000 17 ; Corporation. 
0000 18 ; 
0000 19 ; DEC assumes no responsibility for the use or reliability of its 
0000 20 ; software on equipment which is not supplied by DEC. 
0000 20. 3 
0000 22 3 
0000 23 ; Facility: Example of User Written System Services 
0000 24 ¢+4+ 
0000 25 ; Abstract: 
0000 26 ; This module contains an example of a program that invokes a sample 
0000 27 ; user-written system service that is contained in a privileged 
0000 28 ; shareable image. The module USSDISP contains the sample service 
0000 29 ; and associated dispatching code being invoked by this simple test 
0000 30 ; program, 
0000 31. p=- 
0000 32 ; Link Command File: 
0000 33; 
0000 34 ; $! 
0000 35:3 St Link Command file for USSTEST 
0000 36 ; 4 
0000 ST <3 S$ LINK USSTEST/MAP/FULL,SYSSINPUT/OPTIONS 
0000 38 ; ! 
0000 39 ; ! Options file for USSTEST 
0000 40 ; USS.EXE/SHARE 
0000 41; 
0000 42 ;-- 
00000000 0000 43 BUF: -LONG 0 3; Location to receive TODR contents 
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USSTEST 10-MAR-1980 15:12:23 VAX-11 Macro V02.42 Page 2 
v1.0 Sample invocation of user written system 10-MAR-1980 15:02:56 | DBB2:{HUSTVEDT.USS]USSTEST.MAR;5 (1) 
0004 45 .SBTTL Sample invocation of user written system service 
0004 46 tt 
a004 47 ; Functional Description: 
0004 48 ; This routine shows an invocation of the example user system service that 
0004 49 ; will read the contents of the time of day register. 
0004 50 ; 
0004 Sl As can be seen by this example, the privileged nature of the code used 
0004 523 to implement the reading of the TODR is not visible to the caller. 
0004 53 3 For coding convenience and better maintainability, the code can be 
0004 54; generated by macros patterned on the standard VMS system service macros. 
0004 55; 
0004 56 3-- 
0004 57 
0004 58 
oooc 0004 59 »~ENTRY USSTEST, “M<> 7 Entry mask and definition 
F7 AF 9F 0006 60 PUSHAB BUF 7 Build argument list - set address for 
0009 61 7 return value 
OOOO0COO0O'EF 01 FB 0009 62 CALLS #1,USER GET TODR ; Invoke routine in privileged sh. image 
0010 63 as We 7 to get value from Time-of-day register 
04 0010 64 RET r 
0011 65 
0011 66 «END USSTEST : 
USSTEST 10-MAR-1980 15:12:23 VAX-11 Macro V02.42 Page 3 
Symbol table 1O-MAR-1980 15:02:56 —DBB2:{HUSTVEDT.USS]USSTEST.MAR;5 (1) 
BUF 00000000 R 01 
USER_GET_TODR wakRKRHH XO] 
USSTEST 00000004 RG ol 
4+--~--~----~------- + 
! Psect synopsis ! 
denen ee ee + 
PSECT name Allocation PSECT No. Attributes 
« ABS. 00000000 ( 0.) OO ( O.) NOPIC USR CON ABS LCL NOSHR NOEXE NORD NOWRT NOVEC BYTE 
- BLANK . 00000011 ( 17.) O01 ( 1.) \NOPIC USR CON REL LCL NOSHR EXE RD WRT NOVEC BYTE 
4+---------------+--------- + 
1 Performance indicators ! 
4+--~----------------+----- + 
Phase Page faults CPU Time Elapsed Time 
Initialization 9 00:00:00.05 00:00:00.16 
Command processing 14 00:00:00.18 00:00:00.98 
Pass 1 33 00:00:00.23 00:00:01.11 
Symbol table sort 0 00:00:00.00 00:00:00.00 
Pass 2 a5 00:00:00.14 00:00:00.21 
Symbol table output 0 00:00:00.01 00:00:00.01 
Psect synopsis output 2 00:00:00.02 00:00:00.02 
Cross-reference output 0 00:00:00.00 00:00:00.00 
Assembler run totals 95 00:00:00.63 00:00:02.49 


SHOVWI ATAVSUVHS AIOE TIAIYd 
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The working set limit was 200 pages. 

673 bytes (2 pages) of virtual memory were used to buffer the intermediate code. 
There were 10 pages of symbol table space allocated to hold 3 non-local and 0 local 
66 source lines were read in Pass 1, producing 13 object records in Pass 2. 

0 pages of virtual memory were used to define O macros. 


$--------------------~------ + 
1 Macro library statistics ! 
t-------------------~------ + 

Macro library name : Macros defined 

_DBRAS5: [SYSLIB]STARLET.MLB;1 ‘ 0 


0 GETS were required to define O macros. 
There were no errors, warnings or information messages. 


USSTEST/LIS 


USSLNK .COM 


Command file to link User System Service example. 


LINK/PROTECT/NOSYSSHR/SHARE=USS/MAP=USS/FULL SYSSINPUT/OPTIONS 


Options file for the link cf User System Sérvice example. 


we em oe 1D MD 


SYSSSYSTEM:SYS.STB/SELECTIVE 


Create a separate cluster for the transfer vector. 
CLUSTER=TRANSTER_VECTOR,, ,SYSSDISK: [] USSDISP 

! 

GSMATCH=LEQUAL,1,1 


USSTSTLNK .COM 


Link Command file for USSTEST 


Poe ee 


INK USSTEST/MAP/FULL,SYSSINPUT/OPTIONS 


wee Ue oe 


Options file for USSTEST 
USS. EXE/SHARE 


symbols. 
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USS 


USER_SYS_DISP 
SYS 
SYSVECTOR 


_DBB2: [HUSTVEDT. 


Cluster 


TRANSTER_VECTOR 


_DBB2: [HUSTVEDT. 


Psect Name 


SS$$TRANSFER_VECTOR 


. BLANK . 
EXEC_NARG 
KERNEL_NARG 
USER_EXEC_DISPO 
USER_EXEC_DISP1 


USER_EXEC_DISP2 


USER_KERNEL_DISPO 


USS.MAP 


Ident Bytes 
v1.0 275 
-STB;1 

0221 


USS] USS.EXE;19 


Type Paces 


00000200 


4 al 00000400 


USS] USS.EXE;19 


Module Name Base 
00000000 
SYSVECTOR o0000c0n0 
00000200 
USER_SYS_DISP 00000200 
00000200 
USER_SYS_DISP 00000200 
00000217 
USER_SYS DISP 00000217 
00000218 
USER_SYS_DISP 00000218 
O000021A 
USER_SYS DISP 0000021A 
00000255 
USER_SYS_DISP 00000255 
00000257 
USER_SYS DISP 00000257 
000002B3 
USER_SYS_DISP 000002B3 


10-MAR-1980 15:48 





DBB2: (HUSTVEDT. USS] USSDISP .0BJ;18 


2 QO READ ONLY 
3 0 READ ONLY 
1O0-MAR-1980 15:48 
os + 
! Program Section Synopsis ! 
4-------------------------- + 
End Length Align 
00000000 00000000 ( 0.) BYTE 0 
oooc00000 C00CnONN ( 0.) BYTE 0 
00000216 00000017 ( 23.) PAGE 9 
00000216 00000017 ( 23.) PAGE 9 
00000200 00000000 ( 0.) BYTE 0 
00000200 00000000 ( 0.) BYTE 0 
00000217 00000001 ( 1.) BYTE 0 
00000217 00000001 ( i+} BYTE 0 
00000219 Q0000002 ( 2.) BYTE 0 
00000219 00000002 ( 2.) BYTE 0 
00000254 0000003B ( 59.) BYTE 0 
00000254 0000003B ( 59.) BYTE 0 
00000256 00000002 ( 2.) BYTE 0 
00000256 00000002 ( 2+) BYTE 0 
000002B2 0000005C ( 92.) BYTE 0 
000002B2 O0000005C ( 92.) BYTE 0 
O00002ZED 0000003B ( 59.) BYTE 0 
000002ED 0000003B ( 59.) BYTE 0 


0 ~DRAS: [SYSEXE]SYS,STB;1 
0 ~DRA5: [SYSLIB] STARLET.OLB; 1 


1C-MAR-1980 15:48 


Base Addr Disk VBN PFC Protection and Paging 


L 


Global Sec. Name 


LINKER V02.42 


Creation Date 
O-MAR-1980 15:48 
5-MAR-1980 20:17 
5-MAR-1980 00:11 


LINKER V92.42 


Match 


LINKER V02.42 


Attributes 


NOPIC,USR,CON,REL,LCL,NOSHR, 


PIC,USR,CON,REL,LCL,NOSHR, 


NOPIC,USR,CON,REL,LCL,NOSHR, 


PIC,USR,CON,REL,LCL,NOSHR, 


PIC,USR,CON,REL,LCL,NOSHR, 


PIC,USR,CON ,REL,LCL,NOSHR, 


PIC,USR,CON,REL,LCL,NOSHR, 


PIC,USR,CON,REL,LCL,NOSHR, 


PIC,USR,CON,REL,LCL,NOSHR, 


VAX~-11 Macro V02.42 
LINK-32 V02.42 
VAX-1]1 Macro V02.42 


Majorid 


EXE, 


EXE, 


EXE, 


EXE, 


EXE, 


EXE, 


EXE, 


Page Bl 

Page 2 
Minorid 

Page 3 


RD, WRT,NOVEC 


RD ,NOWRT,NOVEC 


RD, WRT,NOVEC 


RD ,NOWRT ,NOVEC 


RD ,NOWRT ,NOVEC 


RD ,NOWRT ,NOVEC 


RD ,NOWRT ,NOVEC 


RD ,NOWRT ,NOVEC 


RD ,NOWRT ,NOVEC 
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USER_KERNEL_DISP1 OGCOO2ZEE 000002F1 ooc00004 ( 4.) BYTE 0 PIC,USR,CON,REL,LCL,NOSHR, EXE, 
USER_SYS_DISP  000002EE 000002F1 00000004 ( 4.) BYTE 0 

USER_KERNEL_DISP2 000002F2 000002F2 00000001 ( 1.) BYTE 0 PIC,USR,CON,REL,;LCL,NOSHR, EXE, 
USER_SYS_DISP 000002F2 000002F2 00000001 ( 1.) BYTE 0 

USER_SERVICES 00000400 0000041F 00000020 ( 32.) PAGE 9  PIC,USR,CON,REL,LCL,NOSHR, EXE, 
USER_SYS_DISP 060000400 0000041F 00000020 ( 32.) PAGE 9 


_DBB2: [HUSTVEDT. USS] USS. EXz;19 


CTLS$GL_PHD 7FFEFE88 
EXEC_DISPATCH  00000227-R 
KERNEL DISPATCH 000002CO-R 


ss$_ACCVIO ooo0000c 
SS$_INSFARG 00000114 
SS$ NORMAL 00000001 


SYSSK_VERSION 35503058 

USER_GET _TODR 00000258-RU 
USER_NULL 000002AB-RU 
USER_SET_PFC 00000275-RU 


_DBB2: [HUSTVEDT. USS] USS. EXE; 19 


Value 

sat ebcitaalion: 5 

00000001 SS$_NORMAL 
o000000c SS$_ACCVIO 
00000114 SS$_INSFARG 
00000227 R-EXEC_DISPATCH 
00000258 R-USER_GET_TODR 
00000275 R-USER_SET_PFC 
000002AB R-USER_NULL 
000002c0 R-KERNEL_ DISPATCH 
35503058 SYS$K_VERSION 
7FFEFE88 CTLS$GL_PHD 


Key for special characters 
+------------------ + 
! * - Undefined U 
' U - Universal ! 
! R - Relocatable ! 
! WK ~ Weak ! 
$------------------ + 


LINKER V02.42 
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above: 


RD ,NOWRT ,NOVEC 


RD ,NOWRT ,NOVEC 


RD,NOWRT, VEC 


Page 4 
Value 
Page 5 
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_DBB2: [HUSTVEDT.USS]USS.EXE;19 


Virtual memory allocated: 


Stack size: QO. pages 
Image header virtual block limits: be de 1. block) 
Image binary virtual block limits: 2. Bee 2. blocks) 
Image name and identification: USS .STB; 
Number of files: Bie 
Number of modules: om 
Number of program sections: 18. 
Number of global symbols: 9. 
Number of image sections: 4. 
Image type: PIC, SHAREABLE. Global section match = “LESS/EQUAL", 
Map format: FULL in file " DBB2: [HUSTVEDT.USS]USS.MAP;19" 
Estimated map length: 43. blocks " 
$--~---~-------------- + 
! Link Run Statistics ! 
$--------------------- + 
Performance Indicators Page Faults CPU Time Elapsed Time 
Command processing: 9 00:00:00.08 00:00:00.12 
Pass 1: 31 00:00:01.00 00:00:01.79 
Allocation/Relocation: 7 00:00:00.05 00:00:00.19 
Pass 2: 3 00:00:00.22 00:00:00.72 
Map data after object module synopsis: 17 00:00:00.25 00:00:00.70 
Symbol table output: 0 00:00:00.04 00:00:00.33 
Total run values: 67 00:00:01.64 00:00:03.85 


Using a working set limited to 200 pages and 14 pages of data storage 


Total number object records read (both passes): 272 


00000200 OOOO05FF 00000400 (1024, 


LO-MAR-1980 15:48 


bytes, 2. pages) 


(excluding image) 


of which 51 were in libraries and 2 were DEBUG data records containing 414 bytes 


Number of modules extracted explicitly = 0 
with 1 extracted to resolve undefined symbols 


0 library searches were for symbols not in the library searched 
A total of 4 global symbol table records was written 


/PROTECT/NOSYSSHR/SHARE=USS/MAP=USS/FULL SYSSINPUT/OPTIONS 


Ready 


LINKER V02.42 


Ident, Major=l, Minor=1] 
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CHAPTER 7 


PROGRAM EXAMPLES 


This chapter presents applications that use many of the features 
discussed in this manual. Each application is explained, and the 
program listings are given. The programs are in VAX-11 FORTRAN, 
although some routines are in VAX-11 MACRO. 


The following applications are included in this chapter: 


e An analog-to-digital (A/D) data acquisition and manipulation 
system 


e An airline reservations system 


7.1 DATA ACQUISITION AND MANIPULATION 


This system, called LABIO, allows multiple users to receive and 
manipulate analog-to-digital (A/D) data in real time. In this 
example, a 16-channel A/D converter, such as the AD11-K, is shared by 
1 to 16 independent users. This example demonstrates the real-time 
use of many VAX/VMS system services and features (described in 
Sections 7.1.2 and Peles)‘ However, because each real-time 
application is unique, this example does not show the only, or 
necessarily the most efficient, use of these features. It is meant 
only as a guideline for possible implementations. 


7.1.1 Application Overview 


In the LABIO system the 16-channel A/D converter is to be used 
independently by up to 16 users; that is, each user must be able to 
specify collection parameters and collect data from one or more A/D 
channels without conflicting with other users. This independence is 
achieved by placing a single "privileged" process (LABIO DATA ACQ) in 
control of the AD11-K. = 7 


The LABIO DATA _ACQ process collects data from the AD11-K and stores 
the data in “buffers in a shared data array. The process runs at a 
real-time priority and uses the VAX/VMS connect-to-interrupt 
capability to process interrupts from a dedicated KW11-K real-time 
-Clock. On every clock overflow, data from the AD11-K is taken = and 
stored in the shared data array. The process uses control information 
stored in the shared data array to determine how much data is to _ he 
collected for each A/D channel. To protect users from other users 
(and from themselves), the shared data array is read-only for’ the 
users. 
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To store control information in the control block, each user 
communicates with a second "privileged" process, LABIO CONNECT. The 
LABIO CONNECT process receives, validates, and acknowledges each user 
request, and modifies the data base accordingly. Simultaneous 
requests from different users are serialized through the use of 
mailboxes. The mailbox that receives user requests has the logical 
name LABIO CONNECT. Users can issue four types of request: 


e CONNECT 
@ ALLOCATE 
e DISCONNECT 
e@e DEALLOCATE 


The first user request must be CONNECT. This request makes the user 
known to the LABIO system. The user also passes the logical name of a 
mailbox, which the LABIO CONNECT process will use to ackowledge the 
user's requests. ee 


After a CONNECT request is completed, the user can issue ALLOCATE and 
DEALLOCATE requests, The ALLOCATE request is used to gain ownership 
of a specific A/D channel; once a channel is allocated by a user, no 
other users can allocate it until the owner specifies it ina 
DEALLOCATE request. Four parameters are associated with the ALLOCATE 
request: 


e Channel number 

e Sample rate 

e Buffer size 

e Buffer count (number of buffers to be acquired) 


A user can allocate any number of A/D channels. The ALLOCATE request 
can also be used to change collection parameters for a channel a user 
already owns. 


When finished with a channel, a user issues a DEALLOCATE request for 
the channel; and when finished altogether, a user issues a DISCONNECT 
request. The DISCONNECT request removes a user from the LABIO- system 
and implicitly deallocates any channels still allocated to the user. 


Once connected to the LABIO system and allocated channels, a _ user 
communicates with the data acquisition process (LABIO DATA _ACO) using 
event flags. Each channel has three flags associated with it: 


e ACTIVITY flag 
e NOTIFY flag 
e STATUS flag 


The ACTIVITY flag determines whether data collection is enabled (flag 
set by user) or disabled (flag cleared). The user process tells the 
LABIO DATA ACQ process to check the ACTIVITY flag by setting the 
NOTIFY flag; that is, when the NOTIFY flag is set, the LABIO DATA ACQ 
process checks the state of the corresponding ACTIVITY flag and 
enables or disables the channel. When a data buffer is ready for user 
processing, the LABIO DATA_ACQ process sets the STATUS flag for the 
channel. When the user process detects that the STATUS flag is set, 
it clears the flag and processes the data buffer. 
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There is one utility program associated with the LABIO. system: 
LABIO STATUS, which displays the status of each of the A/D channels on 
a VT52-compatible video terminal. 


7.1.2 LABIO System Details 


The LABIO system uses a number of VAX/VMS features described in this 
manual. The following sections describe the major features 
illustrated in this system. 


7.1.2.1 Shared Data Base - The processes share data by using global 
sections. The LABIO DATA ACQ process creates the global section using 
the Create and Map Section (S$CRMPSC) system service. A VAX-11l MACRO 
routine (GBL SECTION UFO) is used to open the data file to be 
associated with the global section. This global section is read/write 
for processes with the same UIC (that is, LABIO DATA ACQ and 
LABIO_ CONNECT), but read-only for other processes in the group (that 
is, the processes running the user programs). The global section is 
not accessible by any processes outside the group. Other processes 
map the global section using the Map Global Section (SMGBLSC) system 
service, specifying the global section name LABIO_COMMON, 


Because global sections are mapped by pages, it is important to ensure 
that the data arrays are page aligned. To ensure this alignment, the 
VAX-11 FORTRAN named-common and block-data features are used with the 
VAX-11 Linker cluster option. 


The shared data region contains three arrays: 


e AD BLOCK, containing 16 control blocks, one for each A/D 
channel 


e CONNECT BLOCK, containing 16 control blocks, one for each 
process that can be connected to the system (each process is 
identified by its process identification) 


e DATA_BUFFER, the array into which the A/D data is stored 


7.1.2.2 Common Event Flag Clusters - Two common event flag clusters 
are used in the LABIO system: 


e LABIO EF NOTIFY, containing 16 NOTIFY flags 


e LABIO EF STATUS, containing 16 ACTIVITY flags and 16 STATUS 
flags 


The LABIO DATA ACQ process waits for the logical OR of the 16 NOTIFY 
flags; that is, the process is activated whenever any of the flags is 
set. Each user process normally waits for the logical OR of the 
STATUS flags for the channels it has allocated. Each user process 
must set and clear the ACTIVITY flags as appropriate, and must set the 
corresponding NOTIFY flag if it wants the LABIO DATA ACQ process to 
check the ACTIVITY flag. The LABIO DATA ACQ process sets the STATUS 
flag when a buffer is ready and stores the buffer index in AD BLOCK. 
The user process is then responsible for clearing the STATUS flaq. 
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7.1.2.3 Mailboxes - The LABIO CONNECT process creates a mailbox with 
the logical name LABIO CONNECT, All user processes write their 
requests to this mailbox. Each user process must also create a 
mailbox, and must specify the mailbox's logical name in the CONNECT 
request. If the LABIO CONNECT process accepts the CONNECT request, it 
opens the user's mailbox and acknowledges the request by returning the 
user request line preceded by a 2-character code: 


@ Zero to indicate a positive acknowledgment 


e Nonzero to indicate a negative acknowledgment (the specific 
code corresponds to the field containing the error) 


7.1.2.4 Connecting to an Interrupt Vector - The actual 
analog-to-digital I/O is performed by an interrupt service routine 
specified in the connect-to-interrupt $QIO call. The process connects 
to the interrupt vector for the KWl1-K real-time clock, which 
generates an interrupt every millisecond. On each interrupt, the 
interrupt service routine does the following for each active AD11-K 
channel (all control information is stored in AD BLOCK): 


l. Decrements the timer for the current channel 


2. If the timer overflows, takes an A/D reading and stores’ the 
result in DATA_BUFFER 


3. If the data buffer is full, switches to the next buffer 

4. If the last buffer has been acquired, deactivates the channel 
If any buffer was filled, an AST is requested and bits 0 to 15 of the 
AST parameter word are set to indicate those channels that had a 


buffer filled. The AST service routine SET_EF_AST sets the STATUS 
event flags corresponding to the channels that had buffers filled. 


7.1.3 Typical LABIO User Program Logic 


A typical program running in a user process in the LABIO system would 
contain the following logical steps: 


1. Map the global section LABIO COMMON 


2. Associate with the common event flag clusters LABIO_EF NOTIFY 
and LABI O_EF_ STATUS 


3. Open the mailbox LABIO CONNECT 


4. Create a mailbox to receive acknowledgments from the 
LABIO_CONNECT process 


5. Issue a CONNECT request and wait for an acknowledgment 


6. Allocate channels using ALLOCATE requests and wait for 
acknowledgments 


7. Start data acquisition by setting the ACTIVITY and NOTIFY 
event flags 


8. Wait for buffer(s) to be filled by waiting for STATUS event 
flags to be set 
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9. Process the contents of the buffers 


10. Repeat steps 8 and 9 until finished 


7.1.4 Program Listings 

This section lists the files needed to create and use the laboratory 
data acquisition application. Three programs that make up the system 
and three sample programs that use the system are presented first, 
followed by modules used by all or some of the programs. The 
remaining files are used to activate the system and to compile and 
link the program. 

The files are presented in the following order: 

l. Three programs that make up the system. The modules in’ each 
program are as follows (LABIOCOM.FOR, listed later, is common 
to all three programs): 

a. LABIOACQ.FOR, GBLSECUFO.MAR, LABIOCIN.MAR 
b. LABIOCON.FOR 
c. LABIOSTAT.FOR 

2. Three sample programs to use the system. The modules in each 
program are as follows (LABIOCOM.FOR, listed later, is common 
to all three programs): 

a. LABIOPEAK.FOR, PEAK.FOR 
b. LABIOSAMP.FOR 
c. TESTLABIO.FOR 
3. Modules used by all or some programs 
a. LABIOCOM.FOR (common routines) 
b. LABMBXDEF.FOR (mailbox format) 
c. LABCHNDEF,.FOR (common data structures) 
dad. LABIOSEC.FOR (common data definitions) 
4. Command procedures to activate the system 
a. CONNECT.COM 
b. LABIOSTRT.COM 
5. Files to compile and link the programs 
a. LABIOCOMP.COM 
b. LABIOLINK.COM 
c. LABIO.OPT 


ad. LABIOCIN.OPT 
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IFiles LASIOACS.FOR 


— e e- c= OO 


— Os oe B= oe 8 B= 8 8 Be 


Program LABIO,DATA,ACO 


This is the program that acquires data for the LABIO system 
It uses the connect=towinterrupt feature of VMS to acquire 
via a user written I/0 routine. The actual I/O routine is 
written in MACRO, The main program monitors the event flags 
and enables and disables data acquisition for each channel, 
It also notifies users via event flags when a buffer is full, 


Define the LASIO data base 
Include “LABCHNDEF,FOR? 


Local Variables 
Logical*4 SECTION FLAGS, SECTION PROT 


System Services 
Logical*4 SYSSASCEFC,SYSSMGBLSC,SYSSASSIGN,SYSS010 
Logical*4 SYS#CLREF 


External) constants 
External SECSM,GOL,/SECBM,WRT,SSS,CREATED, SSS, WASSET 
External SETLEF AST 


Misc, 
Legicalix4 AD CIN, UP,SUCCESS 


Create the Global Section for the data buffer 
This data buffer wil] be READ/WRITE for the owner, READ only for the GRO 


First see if the global section already exists, if it 
does just map to it, ana set the restart fiag, 


If not, Open the Data File, This Can not be opened 
via FORTRAN since we need the VMS channel number, 


SECTION(C1) & %Loc(€ LABIO SUFFERS) {Start address of section 
SECTION(C2) = %Loc( LABIO,BUFFER,E) =~ 1 JLEnd address 

Page count for the section 
SECTION,SIZE = ¢ SECTION(2) = SECTION(1) )/512 + 1 


FLAGS for Section are GLOBAL,SHARED, NON, ZEROED, READ/WRITE, TEMP 
SECTION, FLAGS = &4Loc€ SECSH,GBL ) + ALocl SECHEM, WRT ) 
Try Just manping to the global section 


SUCCESS = SYSSMGALSC( SECTION», ,-4Val (SECTION, FLAGS), *LABIOCOMMON’,, 
If#( SUCCESS ) Then 


RESTART = , TRUE, tSucces, this is a restart 
Else 

SUCCESS = GEL, SECTION ,UFO( SECTION SIZE, *“LABIO,SEC, FILE’, 
4 SECTION, CHANNEL ) 


If( mote SUCCESS } 
1 Call FATAL LERROR(SJCCESS, “Opening Global Section File”) 
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| PROTECTION {s OWNER = READ/WRITE, GROUP = READ, SYSTEM/WORLD = none 
SECTION, PROT = °F E a F°X [Protection for section 

{ Create and Map the Section 

j 


SUCCESS = SYSSCRMPSC( SECTION, , -%Val (SECTION FLAGS), “LABIOCOMMON’, 
1 pe BVal (SECTION, CHANNEL) »%Va] (SECTION, SIZE) oy 
4 *Val (SECTION PROT), %Val (SECTION, SIZE)) 
If( mot, SUCCESS ) 
1 Call FATAL LERROR(SUCCESS, "Creating Global Section’) 
RESTART = ,FALSE, {We are not restarting 
End If 


i 
1 If this is not a restart, clear the data structures 
I 


Tf ,»mot,. RESTART ) Then 


Do 32 1 = 1, MAX AD CHANNEL 1Clear AOD, BLOCK 
Do 30 J = ly 16 
30 AD BLOCK(J,1I) = # 
Do 31 K = t, BUFFER,COUNT iClear Data buffers 
Oo 31 J = 1, MAX BUPLSIZE 
31 DATA, BUPFER(J,K,1I) = a 
32 Continue 


De 33 1s 1, MAX PID 
Do 33 J = lye 
33 CONNECT, BLOCK(I,J) = &@ }Clear Process connect block 
End IF 


- 


Create event flag cluster EF, NOTIFY and associate with event flags 648995 
} These are used £9 motify the ata Acauisition orocess. 


SUCCESS = SYSSASCEFC( ZVALCEF NOTIFY, 1) EF NOTIFY, CLSTRoe) 
Tf € ,mot, SUCCESS) 
1 Call FATAL, ERROR( SUCCESS, °CREATING EVENT FLAG CLUSTER’) 


Create event flag cluster EF,STATUS and associate with event flags 96=127 
These are used to notify and report the status of the user buffers 


— om ee a 


SUCCESS = SYSSASCEFC(C 4VALCEF STATUS, 1),EF STATUS CLSTRey) 
Tf ¢€ snot, SUCCESS) 
1 Call FATAL, ERROK( SUCCESS, "CREATING EVENT FLAG CLUSTER®) 


} Make sure that we can*t be swapped 
Call SYSSSETSWM(%4Val(1)) 
Set*uo the Connect=toeInterftunt 


First assign a VNS Channel for the device 
Then call the conmecteto=interruct setup routine, 


— 2 o- o- oe 


SUCCESS = SYSSASSIGN( "LABIO LAD’, CIN CHANNEL), 3) 
If ¢ ,mot,. SUCCESS ) 
1 Call] FATAL, ERROR( SUCCESS, “assigning 4/)D device’ ) 


SUCCESS = AD CIN, SETUPC CIN CHANNEL, SET EF AST ) 
If€ .not, SUCCESS ) 
1 Call FATAL, ERROR( SUCCESS, *conmectingetosinterrupt”) 


20 


1a 


il 
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End Of Initialization, Notify other processes by setting EF, DATA, ACO 
Call SYSSSETEF( %Val(€ EF ,OATA,ACQ) ) 


Wait for an event flag in the EF,NOTIFY cluster 
Then read the EFLNOTIFY CLUSTER and EF, STATUS, CLUSTER 


Call SYSSWFLOR( &AValCEFLNOTIFY,1) » ¥Val(°’FFFF*X) ) 


Look for the flag(s) set in EF,NOTIFY 

If the corresponding activity flag ig sete activate the channel, 
otherwise deactivate it. Aliso check the buffer status flag, if clear 
clear the buffer index, 


De ee I = 1,16 
Tf€ SYSSCLREF(C “AValCEFLNOTIFY_,OFF + 1)) ,eqe %Loc(SS$,WASSET)) Then 
If( ADL BLOCK(1,1I) «nee @ ) Then 
If€ SYSSREADEF(C &AValCEFLACTIVITY,GFF + L),EFLSTATE ) 


1 2@9, S4Loc(SS#,WASSET ) ) Then 
AD,@LOCK(1,1) 2 ACTIVE 
Else 
AG BLOCK (4,1) = INACTIVE 
Ena if 
If( SYSSREADEF( 4Vai(EF,STATUS_OFF + I),EF STATE ) 
1 eed, 4LOC(SSSEWASCLAR)) AD, BLOCK(7,1) = @ 
Enda If 
End If 
Continue 
Go To 1e@ 
End 


Subroutine SETLEF,AST( EVENT FLAGS ) 


This is a AST routine which {fs invoked poy the 
Interrupt service routine, Tnis routine sets 
the event flags indicated by the ISR, 


Include *“LABCHNDEF,FOR’ 
Integer EVENT FLAGS 


The Event flags are set jin cluster EF, STATUS, CLSTR 


Do 14 I = 1,46 

T¢€ CEVENT,FLAGS ,ana, 6ITCI)) ~ne, & ) 

1 Cal! SYS$SETEF( “VAalICEF, STATUS OFF + I) ) 
Continue 

Return 


Erna 
End of File) 
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eTITLE GBLSECUFO Global Section UFO (User Flle Open) 


sThis routine opens a file to be used as a global section 
zAn RMS OPEN {8 performed with the file options (FOP) of 
sUser File Open (UFO), The calling routine specifies the 
sfile name and number of blocks; this routine returns the 
channel] number on which the file was opened, 

slf the specified file does not exist, the file is created 


3 
sThe calling sequence is 


Call GBLLSECTION,UFOC bilkent,tile=namerchan ) 


Where 
blkent => Number of blocks im the file 
file=name => filename descriptor block 
Chan => channel opened 
Examples 


Integers CraNNneL 
3 


; 
: 
, 
: 
; 
’ 
; 
; 
3 
} 
3 
i 
; 
? 3 

: Cal) GBL SECTION, UFOC1d, “LABIO,DATA,DAT’, CHANNEL ) 
eSBTTL GBL,SEC,UFO 

; RMS FAB for @ SCREATE 


GBLFABs SFAS FACSPUT,= 
FoP=<UFo,CIF,C8T> 


NUM,ARG 3 3 sNumber of arguments 


sENTRY GBL, SECTION, UFO, 0 


MOVL aSSBLINSFARG,RA yAssume bad arg count 
CMPB CAP), BNUM ARG rCheck arg count 
BLSS ExIT :Too few 
MOVL BCAP),RI sGet file name address string deseriptor 
MOVE CR1i),GBLFAB+FABSB FNS Store string lenath in FAB 
MOVL 4(R1),GBLFAB+FASBSL,FNA yAma file name 
MOVL @4CAP),GBLFAB+FABEL ALG Number of blocks to allocate 
SCREATE FAG=GBLFAB ‘Open data file, Create it if 
sif it does not exist 

MOVL GHLFABS+FARSL STV,912C4P) Store channel number 

EXIT: RET sRetuen with error code in R) 
2 END 
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; KWJHIST = 1 
eTITLE LABIO,CIN = LASIO Connect=toerInternupt Module 
pLDENT /VOLS 


P, Programmer 1S5*Nove79 


t++ 
; 

3 FACILITY: 

; 

; LABIO demonstation system 

; 

: ABSTRACTs 

; 

; This module contains the I/0 code for handling 

: an ADLI=K, It is an example of a connecteto interrupt 
; routine, This module contains code to perform the following 
4 

; The start I/0 routine 

7 The interrupt service routine 

? The cancel 1/0 routine 

; 

: AUTHORS: 

; 

; 

; 

: 


2SBTTL DATA STRUCTURES 


ePSECT LABIO,SECTION PIC,OVR,REL,GBL,SHR,NOEXE-RO,WRTs LONG 


+ The following data structures are also defined oy a 
: FORTRAN INCLUDE file, These gefinitions must agree, 


; AD, BLOCK A/D Control Block 
MAX AD, CHANNEL = 16 Number of 4/0 channels 
AD, BLOCK SLOTS = 16 rnumoer of entries in one block 


AD, BLOCK, SIZE = MAX AD CHANNEL *AD BLOCK SLUTS 


sAD BLOCK offsets (long words) 


AD, STATUS Pa) rSTATUS (Unknown, tinactiver or active ) 
ACTIVE Ls 2 y aCTIVE 
INACTIVE ,L = 1 y INACTIVE 
PID 24 3 PIv of connected process 
TICS SAMPLE = 8 + Rate in tics/sanple 
BUFFER SIZE = le ; User specified ouffer size 
BUFFER COUNT = 16 3 User soecified buffer count 
BUFFER, ACG = 2% ? Number of buffers acquired 
VALIO, BUF LIND = 24 3 Index of current valid data buffer 
VALIO, BUF COUNT = 24 3 Numoer of data ooints in last buffer 
CUR, BUF IND = 32 + Index to current aca, buffer 
CuR, BUF COUNT = 36 + Number of data points in last buffer 
TICS,REMAINING = 4¢ : Tics remaining to next sample 
CUR ACO _OFF = 44 3; Offset to aca point 
AD, BLOCK END = 64 ; Offset to eno of a block 
AD, BLOCK: eBLKL AD LBLOCK SIZE 


s DATA, BUFFER Data buffers for LABIO 


MAX BUF COUNT = 2 pNumber ouffers/channel 
MAX, BUF SIZE = Sie2 rmMaximum buffer size (WOROS) 
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BUFFER END = MAX BUF LCOUNT&MAX BUF _SIZEx2 3 Size of ane set of buffers 
DATA,BUF,SIZE = MAX AD, CHANNEL®MAX BUF SIZE*MAX, BUF COUNT 
DATA, BUFFERS eBLKW DATA, BUF,SIZE 


DATA, BUFFER, OFF = DATA, BUFFER@AD BLOCK ;Offset to data buffer from 
sbeginnina of data structure 


: CONNECT SLOCK Process Connect control plock 

MAX, PID = 16 sMax mumber of processes connected 
CONNECT,SIZE = MAX,PID«2 

CONNECT, BLOCK: .JS8LKL CONNECT SIZE 


eS8TTL I/O DEVICES 


tThis section defines the constants asocciated with the KWll#kK clock 
sand the ADL1I=K A/D converter 


KWL LK Clack 
7CSR bit assignments 


KWL1$M,60 = “O01 7G0 bit 

KWLISM,RATE = “Oe sRate = bits 2=4 
KWLISMLINTENG = “0188 pInterrupt enable 
KWILTSMLREADY s “O2u0 sReady bit 
KWILTEMLREPINT = "0480 trepeatea interuupts 


KWII, CSR CONS = KWLLEM REPINTIKALLISM INTENGE KL *KAL LSM RATED 
sRepeated interrupts,interrupt enable 
pRate = | Mg 


KWI1,PRESET = Liae, rPreset => Interrupt rate of 1 KHz 
KWiJ,A, BUFFER = “02 ;Qffset te clock A preset buffer 
KWLI,A, COUNTER = "O24 pGffset to clock A counter 


sADL1=K A/D converter 


ADIL OFFSET = a4 : Offset to the ADLI from the KWii clock CSR, 
ADLI, SUF = 2 3 ADL ouffer offset from ANDLI CSR 

AD11,60 = 4 3; Go bit 

ADL1, MUX INCR = “O4ue + MUX Yner bit 


ADLI,CSR, CONS AD11, G60 Initial CSR valyve 
sLimit for stopoing ISR loon 


ADLILZLOOP, LIMIT = ADLI MUX INC ReMax LAD CRANNEL@ £2 hAD11, CSR CONS 


SIOBDEF 3 Cefinition for I]/0 drivers 
$UCBDEF : Oata structurs 

S$IODEF + I/0 function codes 

BCINDEF + Connecttorinterrupt 
SCRADEF 7 CRB stuff 

SVECDEF 7 more 


eSBTITL LABIC CIN START, Start I/G routine 


p++ 
; LABIO,CIN, START = Starts the Kv11=k 
: 


Functional description: 
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This routine starts the KwWil]=K 
Rate = | Khrz 
Repeated jinterrunt 


Inputs: 

“(R2) ~~ arg count of 4 

4(R2) - Address of the process buffer 

B(R2) = Address of the IFP (1/0 request packet) 

12(0R2) = Address of the device’s CSR 

16(R2) = Address of the UCB (Linit control plack) 
Outputs: 

none 


The routine must preserve’ all registers except RU=R2 and Rd, 


Se i et el el i ee a eT] 


ePSECT LABIO CIN 


LABIO,CIN,START3s$ 


MOVL Le(F2),R4 3 Get address of the Kwit CSR 
CLRW (KU) > Clear the Clock 
MNEGW #KANLI,PRESET,= 3 Preset count ouffer 
KHIL A, BUFFER (RG) 
MOVW HKALI,CSR CONS+KmH115™,G0,(Ri*) 3 Set the bits for 


Repeated interrupt 
Interrupt Enable 


~~ 3 ee 


Got 
MOVW ASSPLNORMAL,R@ + Load a success code into RG, 
RS# ? Return 


eSBTITL LASIO CIN INTERRUPT, Interrupt service routine 


+ 
+ 


LABIO, CIN, INTERRUPT 
Functional description: 


Inputs: 

™O@(R2) © ara count of 5 

4(R2) ~~ Address of the orocess buffer 

8(R2) = address of tna AST parameter 

12(82) = Address of the sevice’s CSR 

16(Re2) = Address of tre IDB Cinterrunt dispatch hlock) 

@u(R2) = Address of tme UCS (init control olock) 
Outputs? 


Sets these hits in the AST parameter for those 
channels who had a buffer fillea 


The routine must oreserve all registers except KieRY 


wk Ne Te Te Ne Ne Re Ne Ne NA Te we Te Be te Ne he we Be TH 


e 
+ adil 


CIN, BUF ADO = 4 pAddress of CIN buffer 
AST,PARM = 4 ;Offset to AST earreter address 
CIN,CSR ADD = 12 rAddress of CSR 
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; 
AD LOOP, DATA! 
1$3 TST8 (R4) wait for A/D conversion 
BGEG 1$ } 
oIF NDF Kw HIST sTime histogram don’t store actual data 
MOVW ADLI,BUF(R4)-(R1) [RY] ystore data point in buffer, 
sA1l done with this channel, setup for the next 
; 
AD,LOOP,NEXTS 
ADOL HAD BLOCK END,RS yNext channel block 
ADDL ABUFFER,END,R1 tNext buffer 
ADOw HADLILMUX INCR,R6 tIner ASO MUX 
AOBLSS S*AMAX LAD CHANNEL,R3,= 3 3Next chranne) 
AD, LOOP 3Bre (ff mot done 
sExit routine = If any buffer overflowed, queve an AST 
MOVL @AST PARM(R2),RU r1f any bit in the AST parameter 
BEGL 1$ i868 set we must queue an AST 
MOVL #1,RQ + 1 means queve the AST, @ means don’t 
iSs POPR H*MEKR5,RO> 3 Restore R5,R6 
RSB } 


eSBTTL LABIO,CIN, CANCEL, Cancel) I/0 routine 


++ 
+ LABIO,CIN, CANCEL, Cancels an 1/0 operation in progress 


3 Functional descriptions 

3 

; This routine tupns off the KwilsK 

3 

, Inputes 

; RS = Addr of the uCé& 

; 

3 Outputss 

; 

} The routine must preserve al] registers except R@eR3, 

; 

; 

je 

LABIO,CIN,CNCL 32 
MOVL UCBSLLCRB(RS),Rb ; Get Adaress of the CRB 
MOVL CROSLLINTOFVECSL  IDB( RA), RO pAddress of the IDB 
MOVL IDBSL CSR(RO),R" 3 Get addr of KWit 
CLRW (RA) : Turn of the KW11 
MOVW #8S$ NORMAL ,RY 3 And return 
RSB 


eSBTTL LABIO,CIN ESO, End of Module 


s++ 
3 Label that marks the end of the moaule 


jee 


LABIO,CIN END: s Last location in module 
eSBTTL AD, CIN SETUP Setsuo routine for LABIN connectetorinterrupt 
3+ 

3 This routine issues the SI0 to connect to the A011/KW11 interrupts, 


LABIO,CINAINTS?# 


PUSHR 
MOVL 
MOVL 


MOVAL 
MOVAL 


MOVW 
CLRL 
CLRL 


AD, LOOP: 


: While the A/D is converting, 
the offset to the data pointer, and update it, 


CMPL 
BLSS 


SOBGTR 


MOVW 
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HOMERS, RO> 
CIN, CSR,ADD(R2),R4 
CIN, BUF, ADD(R2),R5 


DATA, BUFFER, OFF(RS) »R1 


ADLL, OFFSET(R4)-R4 


HADI, CSR CONS, R6 
@AST PARM(R2) 
R3 


(RS), S*#ACTIVE,L 
AD,LOOP NEXT 


sService device { 


mterrupt, save RS,R6 


pAddress of the KWii CSR 
yAddress of AD, BLOCK, control block 
tfor each A/D Channe} 


Oata Buffers 


pAddress of the ADL1i CSR 


yA011 CSR bits, 


GO bit on 


sZero the AST parameter 


sIs this channel] 
No, 


TICS,REMAINING(RS) pAD, LOOP NEXT 
10ecr the timer for this channel 
1Be if no conversion required 


R6,(R4) 


eIF DF KW HIST 


MOVZWL 
ADOW 
INCW 
eENDC 


get 


sStart conversion, 


yTime histogram, 


active? 


try next channel 


while that’s going o 
etored in data buffer 


KWILLA,COUNTER@ADII LOFFSET(R4),RG yGet current clock contentea 


HKWLL,PRESET, RQ 
(R1) (Ra) 


+ action if we have buffer overflow, 


sBuffer overflowed, 
simerement acquired buffer count, 


2s 


. 
, 


MOVL 


MOVL 
TNCL 
AOBLSS 


MOVL 
MOVL 


MULLS 


CLRL 
AOBLEO 


MOVL 
CLRL 

: INSV 
AQBLSS 


TSTL 

BEGL 

MOVL 
H 


TICS SAMPLE(RS),= 
TICS, REMAINING(RS) 
CUR, ACG, OFF(R5),R@ 
CUR, ACQ, OFF(RS) 
BUFFER, SIZE(R5);° 
CUR, BUF ,COUNT(R5),© 
AD,LOOP, DATA 


CUR, BUF, IND(R5),© 
VALID, BUF ,IND(R5) 
CUR, BUF, COUNT(R5),= 
VALID, BUF , COUNT (RS) 
CUR, BUF, INO(RS),= 
MMAX BUF SIZE,= 
CUR, ACG, OFF (RS) 
CUR, BUF, COUNT(R5) 
#MAX, BUF COUNT; = 
CUR, BUF ,INO(RS) 618 
#1,/CUR, BUF, IND(RS) 
CUR, ACG, OFF (RS) 
41,R3,41,9AST PARM(R2) 
BUFFER, COUNT(P5),= 
BUFFER, ACQ(R5),23 
BUFFER, COUNT(R5) 

2s 

#INACTIVE,L, (R5) 


Nowe get the data point and store it 


reset date pointer, 
termimate channel 


Cale time from { 
tAdd one to that 


sReset timer for 


Atgerrupt 
time bin 


the tic counter for this channel, 
Take appropriate 


this channel 


1Get {mdex to next date point 


sAdvence it 


+Updete current data count 
Bre if no buffer overflow 


reset buffer pointer 


vod { 


f done 


Valid cata buf available for user 


Number of points in buffer 


yOffset to next data point 


wReset data count 


Next buffer index 


yMpap=around, 


reset buffer index 


tAnd buffer offset 


ret bit 


in AST parameter word 


Incr puffer count 


Done with all 
sift original 
Don’t stoo 


ouftfers? 
count was zero 


Deactivate channe) 


in the puffer, 
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+ It takes care of the internals associated with the conmectetorinterrupt 
7 QI0, Input parameters the V4S channel and the AST service poutine address, 
7 The connect=toeinterrupt GIO condition code is returned, 

ePSECT AD,CIN, SETUP 


AD, CIN SETUPS: 


2¥ORD ] 
MOVE B(AP)-USER AST 7Get the user AST routine addr 
AD CIN, GIO: 
$QTO,S CHANZ@U(AP),= sChannel 
FUNCRATOS,CONINTARITE,= sAllow writing to the data buffer 
TOSBEAD CIN, TOSB,= 71/0 status Block 
PLSAD CIN, BUF DESC, sBuffer descriptor 
P2RHAD CINLENTRY,= rEntry list 
P3SKAD CIN, MASK,= pStatus bits,etc 
PUSHALD CIN AST, tAST service routine 
PezAit rereallocate some AST control blocks 
RET yReturn to caller 
AD CIN, BUF DESC: rhuffer deserjiptor for CIN 
» LONG LABIO CIN ,ENDMAD BLOCK Size of buffer and CIN handler 
«LONG AD BLOCK rAddress of buffer 


AD CIN, ENTRY3 
e LONG v tNao init code 
e LONG LABIO, CIN STARTSAD SLOCKsStart code 
eLGNG LABIO, CIN, INTSAD BLOCK yleaterrupt service routine 
eLONG LABIO, CIN, CNCL#AD , GLOCK 31/9 cancel routine 


AD, CIN, 1086: 
2 LONG ite 3 I/O Status Block 


: Control mask 


AD,CIN,MASK = CINSM,REPEATICINSM STARTICINGM, ISRICINSM, CANCEL 


=e 3 


AD CIN, AST 


This AST routine calls the user AST routine, The user routine 

cam not be called directly because the AST parameter itself 

mot its address js returned vie the connectetorinterruot routine, 
This routine simply calls the user routine with the ADDRESS of 
the AST parameter, 


~e te we te ts 


AD CIN ,AST33 
«WORD a 
PUSHAL 4CAP) Get the AST carameter addr 
CALLS 8 t,FUSER LAST sCall the USERK routine 
RET 


USER, AST? 
el ONG rAdgr of the user AST routine 


eENV 
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HFiles LABIOCON,FOR 


-_ 


ee ee oe 


Program LABIO, CONNECT 


Define Labio data structures 
Include *LABCHNDEF,FOR® 


Mailbox Definitions 

Include “LABMNBXDEF, FOR? {hefines Mailoox Data Structures 
System Service Definitions 

Logical*4 SYSSCREMBX,SYSSASSIGN 

Logicalx4 SUCCESS 

External SSS ,ENDOFFILE 
Subroutine Definitions 

Integer CONNECT,DISCONNECT, ABORT, ALLOCATE, OEALLOCATE 


Integer READ MAILBOX, wRITE,MAILBOX,LABIO,LOG, ACKNOWLEDGE 
Integer CHECK,PID, RETURN, CODE 


Command Data Structures 


Parameter MAX COMMAND = 5S 

Characterx1S COMMAND, COMMAND, TABLE C( MAX COMMAND) 
Data COMMAND, TABLE /°CONNECT%, 

1 “DISCONNECT %, 

i “ABORT, 

1 “ALLOCATE, 

1 “DEALLOCATE */ 


Map to the Global Data Section "LABIO, COMMON? 
And Define the Cammom Event Flag Clusters 
Request write access to the data base, 


Call LABIO,INIT ( 1) 


See if mailbox LABIO, CONNECT exists by attempting to assign it, if 
it does not exist, create it, Tris mafilnox {s used to communicate with 
other LABIO processes, HKestrict {it to orocesses within this group, 


SUCCESS = SYSEASSIGN(*LABIO, CONNECT’, MBX CHANNEL? , ) 

If (.enot. SUCCESS ) Then 
SUCCESS = SYSECREMBX(, MEX CHANNEL pe pe KVal (OF OUH x) ee "LABIO,CUNNECT 
If (mot, SUCCESS) 

{ Call FATAL,ERROR( SUCCESS, *Cresting mailbox’) 

Ena If 


Tell other orocesses that we’re ready to ga, 
Call SYSSSETEFC éval€ EF,COUNECT ) ) 


Get a command from a peauesting processes 
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1@ Call READ MAILBOX {Get a message 
Call CONNECT CHECK }Check the database to clear 
lany deleted processes, 
| 
1 1lf 1/0 status {ts EQF then process has terminated, ABORT it. 
I 
If ( MBX TO ,STATUS ,eq, *Loc(SSi,ENDOFFILE) ) Go To 23 


L Decode characters aS a command 
rt 


Tf ( MBX ,MESSAGE,L ,ea. &@ ) Go To 1¢ 
Decode (MBX, MESSAGE L,14e,M8X MESSAGE,ERR=14) COMMAND 


H 
} Search Command Tabie for Command 
! 
Do 11 COMMAND INDEX & 1,MAX COMMAND 
Tf( COMMAND ,eq, COMMAND TASLEC COMMAND, INOEX) 9 Go To 12 
li Continue 
Go To 13 !Iltlegal command 
H 
1 Dispatch to correct routine 


la Go To (21-22723,24725) COMMAND INDEX 


! 
1 If we get heres, it*s an unknown command 


i3 Call LABIO,LOGC1) 


} 
$ CONNECT command 
\ 


21 RETURN,CODE = CONNECT (MBX PID) 
Call ACKNOWLEDGE( RETURN COVE )} thcknowleage the reauest 
Call LABIO,LOG ¢ RETURN, CODE ) ILog the acknowleagement 


H 
! Disconnect jf was bad connect 


If (RETURN COLE .ne,  ) Call YISCONNECT (#4) 
Go To 14 


1 DISCONNECT Command 
I 


22 RETURN CODE = DISCONHECT (MEX, PID) 
Call LABIO,LOG ( RETURN CODE ) lLog the acknowledgement 
Go To 1h 


! 
| ABORT commana 
j 


23 RETURN, CQOOE s AsaRT (46x Pi) 
Go To 4¢ 
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i 
1 ALLOCATE command 
t 


24 RETURN,CODE = ALLOCATE (MBX PID) 
Go To 48 


I 
1 DEALLOCATE command 
t 


25 RETURN CODE = DEALLOCATE (MBX,PID) 
Go To 48 


I 
1 Return status in first character spasition 
i 


4u Call ACKNOWLEDGE( RETURN,CODE ) LAcknowledge the request 
Call LABIO,LOG( RETURN CODE ) lLog the acknowledgement 
Go To 18 

§ 

l Formats 

i 

iae Format (A) 
End 


Subroutine CONNECT CHECK 


This routine checks to make sure aj] processes 
connected Cin CONNECT BLOCK) actually exist, 
If a process has been deleted, this routine 
removes it from the database by calling AGORT 


— ee ee 


Include “LABCHNDEF FOR? 
Logical*e4 SYSSGETJPI 


Do 14 I # i, MAX PIO 
PID = CONNECT BLOCK(I, 1) 
If ( PID ,ne, @ ) Then 
I#€ smote SYSSGETJPICZVal(2),PIDs-p4eee) ) Call ABORTC PID ) 
End If 
19 Continue 


Return 


End 
Logicals4 Function READ, MAILBOX 
I 
1 This routine reads the LABIO, CONNECT mailbox 
! Returns when a message is peady 
i 


External IOS, ,READVBLK 
Include “LABMBXDEF,FOR* 
Logicalx4 SYSS$HTO4,SUCCESS 
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{ Read for a message from another process 
j 
MBX ,READSZLOC CIOS READVBLK) 
MBX,MESSAGE(1) = ”% % 


READ, MAILBOX = SYS#QIOW(,%Val (MBX CHANNEL) »%Val (MBX,READ), 


1 MBX, ITO,STATUS,,, MBX, MESSAGE, 
1 4AValCMAX MESSAGE) peony) 
Return 

End 


Logical*4 Function WRITE, MAILBOX (MBX CHAN, MESSAGE, MESSAGE, LENGTH) 
1 This routine writes a message to a mailbox 
! Input are the MBX channel, the message, and message length 
j 

External IOS, WRITEVELK, IOSM,NOW 

Logical SYSS$QI0 


t Weite response buffer of MBX 
{ 


MBX,WRITE =%Loc(IOS,WRITEVBLK) #%Loe(TOSM,NOW) 


WRITE,MAILBOX = SYSSQTOQ(,4Val (MEX CHAN) -2ValC(MBX WRITE) orgs 
1 MESSAGE, %Val (MESSAGE, LENGTH) pp oe) 


99 Return 


End 
Logi¢calx4 Function OPEN, MAILBOX (MAILBOX, CHAN, MAILBOX, NAME) 


1 This routine opens mailbax indicated by MAILBOX,NAME, It returns 
l the VMS channel number assigned to jit, The mailbox name can be 
t padded on the right with blanks, 


Characterx(*) MAILBOX NAME 


Integer MATLYOX CHAN 
Logical*4 SYSSASSIGN,SUCCESS 


H Determine length of mailbox name string 


MAILBOX,NAME LeIndex(MAILBOX,NAME,” "Je 
If (MAILBOX,NAME,L alt, @ ) MAILBOX,NAME,LeLen(MAILBOX, NAME) 


Assign a channel to mailbox 

I Returm status to caller 

OPEN, MAILBOX SSYSSASSIGN(MAILBOX, NAME (: MAILBOX, NAME,L) » MAILBOX, CHAN? >) 
Return 
End 


Subroutine ACKNOWLEDGE (ACK, CQDE) 
I 
| This routine acknowlegdes a request of process, by return the 
! command string the process sent use The string is preceded 


7-19 
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1 an acknowledge code (ACK,CODE), The acknowledgement is sent 
via the mailbox the the sending processes had created, 
1 If that process has not connected to uss we do nothing, 


~“~ 


Include “LABCHNDEF,FOR*’ 
Logical*4 WRITE MAILBOX 


Include “LABMBXDEF,FOR* 
Integer CONNECTLINDEX,CHECK PID, ACK CODE 


| If process js not in CONNECT SLOCK, do not respond, 
CONNECT, INDEX = CHECK, PIOCMBX PID) 
If CCONNECTLINDEX ,ne, @ ) Then 
Encode( MBX RESPONSE, L,140,4BX RESPONSE) ACK, CODE 
MAILBOX = CONNECT, BLOCK(CONNECT INDEX, 2) 
Call wRITE,MAILBOX( “AILSOX, MBX RESPONSE, 
1 MBX MESSAGE, L + MBX RESPONSE L ) 
End If 
Return 
10a Format ( Te ) 
End 
Subroutine LABIO,LOG( CODE ) 
This routine logs a message that has been processed, The message 
is written to the log file, along with the timer process ID, 10 status 


word ang the message length, This routine opens the log file 
if it hasn’t been onened, 


— oe Oe oe ae 


Include “LARMSXCEF, FOR? 


Character*2d TIME 
Logical LOG,OPEN 
Integer CODE 


Data LOGLOPEN/, false./ 
Call} SYSSASCTIMC,/TIME,,) {Get the date and time 


t 
Ll Open Log file if this {ts the first time thru 
rt 
If € snot, LOG,OPEN ) Then 
Open (Unit = te Namex*LABIO,LOG’, Typez*’Unknown’, Access = *Anpenc 
LOG,OPEN = ,True, 
Wefte (1,160) TIME,’ Labio Leg Opened’ 


End If 

10 Wedte (1,200) TIME,MBX PID, MBX, IO,STATUS, 4BX, MESSAGE Le 
1 CODE, (MBX, MESSAGE (I), 151, MBX, MESSAGE L) 
Return 

10¢ Format( 2A ) 
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208 Format( A,Z14,Z18,T10/1T3,128A1 ) 
End 
Integer Function CONNECTCREG PID) 
Include “LABCHNDEF, FOR? 


Include “LABMBXDEF,FOR? 
Characterx63 MAILBOX, NAME 


Integere4 REQ PID, CHECK,PID 
Logical*4 OPEN, MAILBOX 


CONNECT = 1 


t 
1 Find am empty CONNECT BLOCK slot 
! 


Do 109 I s ty, MAX PID 
Tt € CONNECT ,BLOCK(I,1) ,»eae 8 ) Go To 28 
10 Continue 


l We shoulda never get here, since the last slot of 
} the CONNECT BLOCK is a spare for sending message 
} disallowing a conmect} 


Go To 99 


| 
L Open user specified MAILBOX 
§ 


20 Decode (MBX MESSAGE, L,140,M8X, MESSAGE) MATLOOX NAME 
Tf€ wmot, OPEN, MAILBOX( MATLBOX CHAN, MAILBOX, NAME) ) Go To 99 


{ 

bh Allocate the cennect block, if it is not a duplicate 

1 PID, store the PID and mailbox channel in CONNECT, BLOCK 
L If it is a duolicate, store the PID ag =1, 


L¥( CHECK PID(REQ,PID) .ea, & ) Then 
CONNECT, BLOCK(I,1) = REQ,PID 
CONNECT = a 


Else 
CONNECT LBLOCK(I,1) = =1 fDuplicate PID) we will Disconnect 
tAfter Acknowledging request 
End If 


CONNECT, BLOCK(I,2) = MAILBOX CHAN 


If € I ede. MAX {PID ) CONNECT = 1 Jaq room for process] 


99 Return 
120 Format(15xX,A) 
Eng 


Integer Function DISCONNECT(REW, PID) 


lt This routine disconnects a process from the LASIO system, 
iit it is a valid process, all channels still allocated are 


99 


a a 8 ee 8 8 ee 


PROGRAM EXAMPLES 
deallocated, the request {is acknowledged, the channel assigned 
to the mailbox is deassigneds and the CONNECT BLOCK entey is removed, 


Include *LABCHNDEF,FOR*’ 
Integer*4 REG PIO,CHECK PID 


DISCONNECT = 4 
Find index {nto connect block 


CONNECT, INDEX & CHECK PID(REG PID) 
If (CONNECTLINDEX eq, 4 ) Go To 99 INot connected 


Deallocate all A/D channels 
Call DEALLOCATE ALL CREQ PID) 
Acknowledge DISCONNECT request 
Call ACKNOWLEDGE(@) 
Close the majlbox, and zero CONNECT BLOCK 
Cal) SYSSDASSGN( 4Val (CONNECT BLOCK (CONNECT INDEX,2)) ) 
CONNECT, BLOCK (CONNECT,INOEX,1) = @ 
CONNECT, BLOCK(CONNECTLINOEX,2) = 
DISCONNECT =2 


Return 


Erd 


Integer Function ABORT(REG,PID) 
Call DISCONNECT( REG,PID ) 
Return 


End 
Integer Function ALLOCATECREQ,PID) 


This routines allocates an A/D channel to a specific process. 
The process request a channels by nmumper (lelo), specifing 

the asample rate in tics/samoler the ouffer size in words, and 
the mumber of buffers to acquire ( 3 = infinity J). The user can 
default the rate to 1 tic/sample, Default the buffer size ta 
the maximum, and the buffer count to 4, If the user reallocates 
the channel, the defaults are the previous values allocated, 
The channel must been INACTIVE ff it {8 reallocated, 


Include “LABCHNDEF,FGR?’ 
Incluge “LASMBXDEF,FOR?’ 


Imteger*4 REQ PID {PID of requesting process 
Integer*4 PARN(4) 14 input parameters 

Integerse CONNECT INDEX, CHECK PID 

Integertd REG, AU CHAN, REG, TICS, REG, SUF,SIZE,REQ, BUF, CUUNT 
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PROGRAM EXAMPLES 


Logical CHECK, P ARM 


Get index into CONNECT BLOCK for REQ, PIG 
Tf index {s not >» @ » ignore request 


ALLOCATE = 4 [Checking first field 


CONNECT, INDEX = CHECK, PID(REG,PID) 
If € CONNECT,INDEX ,1e,. 4 ) Go To 99 {Req, Proc mot connected) 


Decode message into four fields 

Decode ( MBX, MESSAGE .L,190,MBX, MESSAGE) PARM 

REQ, AD, CHAN = PARM(1) lReaquested A/D channel is first parm 

REQ, TICS = PARM(2) iTics/sample is 2nd 

REG,BUF SIZES PARM(3) l8uffer size {s 3rd 

REG BUF ,COUNTSPARM(4) «Number of buffers is 4th 

ALLOCATE = 2 {Check next parameter (channel number) 
Valid channe! numbers are ij#16 


If (REQLAD,CHAN ,ite. 1.0%, RED,ADCHAN gt. 16) Go To 99 


Requested channel] must mot allocated, or 
allocated to the requesting process 


If ( AD, BLOCK(2,REQ,AD, CHAN) «ne. Y yand, 
1 AD, BLOCK(2,REG,AD, CHAN) .ne, REG,PID ) Ge To 99 


The channel must not be active 
If CAD, BLOCK(1,REG,AD CHAN) ,.gt, INACTIVE ) Go To 99 


ALLOCATE = 3 {Checking mext parm (Tics/sample) 
Tics/sample must be between 1 and 27311 


If( emote CHECK, PARM(REG, TICS, AD, BLOCK(3,REQ, AD, CHAN)» 
1 1, °TFFFFFFF%X,1) ) Go To 99 


ALLOCATE = 4 IChecking parmeter (Buffer size) 


Buffer size between 1 ano MAX BUF, SIZE 


If( amot, CHECK, PARM(REG, BUF SIZE, AD, BLOCK(4,REG,AD, CHAN) » 
i 1,MAX BUF SIZE, MAX, BUF,SIZE) ) Go To 99 


ALLOCATE = 5 { Checking next parameter (number of buffers) 


Number of buffers to acquire must be between 1 and 2™31"1, or 
zero to indicate no limit 


If ( enot, CHECK, PARM(REG BUF, COUNT, AD, SLOCK(S,/REGLAD, CHAN)» Ly 
1 “7FFFFFFF’x,3) ) Go To 99 


ALLOCATE = @ lEverything is acceptable 


Enter info into AD BLOCK 


1 Clear 


99 


100 


PROGRAM EXAMPLES 


AD, BLOCKC1,REQLAD CHAN) s 2B tLock the data base 
assocjated event flags 


Call SYSS$CLREFCZVal( EFLNOTIFY,OFF + REG LAD, CHAN ) ) 
Call SYSSCLREFCZVal( EFLACTIVITY,OFF + REQ,LAD CHAN) ) 
Call SYSSCLREF(XVal( EFLSTATUS OFF + REG,AD CHAN ) ) 


AD, BLOCK (2/REQ,AD, CHAN) 
AD, BLOCK (3,/REG,AD CHAN) 
AD, SLOCK(4,REG,AD, CHAN) 
AD, BLOCK (5, REG, AD, CHAN) 


REG PIO [Requesting PID 

REQ, TICS ITics/sample 

REG, BUF SIZE Requested buffer size 
REQ, BUF COUNT [Number of buffers to acqu{ 


Ce 


AD, BLOCK C6,REG,AD CHAN) a INo buffers acquired 

AD, BLOCK(7,REQ, AD, CHAN) G INo Gata buffer available 
ADL BLOCK (A,REQ, AD CHAN) = &@ {Number elements {nm last by 
AD, BLOCK (9,REGLAD CHAN) 1 Current buffer index 

AD, BLOCK(CIM,REQ LAD, CHAN) = 4 iCurrent buffer count 

AD, BLOCKCII,REGQ LAD CHAN) = 1 {Tics remaining 

AD, BLOCK(12,REQ,AD, CHAN) = 4 LOffset to next data point 
AD SSLOCKCL,REQLAD, CHAN) = INACTIVE {Channel is inactive 
Return 

Error return 

Return $Raturn to caller 


Format(15x,41) 


End 
Integer Function DEALLOCATE(CREQ PID) 


lL This routine deallocates a channel previously allocated by 
! a process, the channel must be INACTIVE when ceallocated, 


Include “LABCHNDEF,FOR*’ 
Inchuge “LABMEXOCEF,FOR® 


Integer*®4 REG PID IPID of requesting process 
Integerx2 CONNECT L INDEX, CHECK PID 
Integer*xd REQLAD CHAN 


$ Get index into CONNECT BLOCK for REG,PID 
! If ingex jig not > @ » {ignore request 


i valid 


DEALLOCATE = i IChecking first field 


CONNECTZINDEX = CHECK PIOCPID) 
If ( CONNECT,INDEX .le. @ ) Go To 99 


DEALLOCATE = 2 
Decode (MEX MESSAGE Lp 14G,MBX MESSAGE) REG LAD CHAN 
channel] numbers are 1-16 


If (REQ,AD CHAN .1t, 1 core REG,AL,CKAN at, 16) Go To 99 


t Does requesting process own the channel? 


DEALLOCATE = 21 


PROGRAM EXAMPLES 


T¢# CAD, BLOCK(2,REQ,AD, CHAN) ,ne, REG,PID ) Go To 99 


t! Is the channel inactive, clear the channel parameters 
DEALLOCATE = 22 


Tf ¢ AD, BLOCK(1,REQ, AD, CHAN) ,ne. INACTIVE ) Go to 99 
Call AD, CANCEL (REG LAD CHAN) 
DEALLOCATE = @ LEverything OK 
Return 
i 
! ERROR return 
1 
99 Ratuen 
{ 
1 This entry point is used to deallocate all channels 
l allocated to a specific process, 
Entey DEALLOCATE, ALL CREQ PID) 
DEALLOCATE = 1 
b Valid PID? 
CONNECT, INDEX & CHECK, PIDCPIN) 
If € CONNECTLINDEX «me. @ ) Then 
{ Look for al) A/D channels allocated to process 
1 ano cancel all I/0 unconditionally, 
Do 19 AD CHAN = 1, MAX AD CHAWNEL 
T# € AD, BLOCK (2,AD, CHAN) eq, REV PIO ) Call AD, CANCEL (AD CHAN) 
12 Continue 
DEALLOCATE,ALL = @ 
End If 
Return 
1a¢ Format(15x,115) 
End 
Integerk4 Funetion AD, CANCEL( CHANNEL ) 
{ Clears the parameter table associated with A/ii channel 


Include °LABCHNDEF,FOR® 
Integer CHANNEL 


AD CANCEL = 1 lAssume error 
j 
1 Legal channel numbers are iel6 
I¢# € CHANNEL .ge, 1 gand, CHANNEL ,le, 16 ) Then 


! 
lL Zero the AD, BLOCK for this channel 
H 


Do 1@ J = 1, 16 {Clear everthing 
19 AD, BLOCK(J, CHANNEL ) = ¢ 
AD, CANCEL = 4 tEverything ok 
Ena IF 


{ 


PROGRAM EXAMPLES 


1 Clear associated event fiags 


t 


99 


99 


1a 


Call SYSSCLREF(%Val( EF,NOTIFY,OFF + CHANNEL ) ) 
Cal) SYSSCLREF(ZVal( EFLACTIVITY,OFF + CHANNEL ) ) 
Cal) SYSSCLREF(%Val( EF,STATUS,OFF + CHANNEL ) ) 


Return 


End 
Logical Function CHECK, PARM(IVAL,QVAL,MIN, MAX,DEFAULT) 


This routine validates and defaults an input parameter (IVAL) 

If IVAL is not @, it compares it ta MIN and MAX, returning TRUE or FALSE, 
If IVAL is @- and OVAL {8 not zero, IVAL = OVAL 

If IVAL is @, and OVAL 18 zero, IVAL = DEFAULT 


Integer*& IVALsOVAL.MIN, MAX,DEFAULT 
CHECK PARM = , false, lassume the worst 


If CIVAL ,ne, @ ) Then 
T#C IVAL glt, MIN gor, IVAL eat. MAX) Go Te 99 
Else 
If (OV4L ~mne, & ) Then 
IVAL = OVAL 
Elise 
IVAL = DEFAULT 
End If 
End IF 


CHECK, PARM = ,true, 
Return 


END 
Integer Function CHECK PIOCPID) 


This routine checks to see if a PID is in CONNECT, BLOCK 


is, the INDEX into CONNECT, BLOCK is returned, If 


it fiasm’t, @ is returned 


Include *LABCHNDEF,FOR® 
Integerx4 PID 


Assume PID is mot in databage 


CHECK,PID = @ 


If PID is found, return index, 


Po 14 Is 1 , MAX,PIO 
If#( CONNECT BLOCK(I,1) wea, PID ) CHECK PIO = I 
Continue 


Return 
End 
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PROGRAM EXAMPLES 


LABIOSTAT,FOR 
Program LABIO,STATUS 


This is a utility routine for the LABIO system, It displays 


the 
the 
The 
one 


The 


status of al] 16 channels of the A/D, It assumes that 
terminal is a VT52 or an equivalents e.g VT194 in VT52 mode, 
display {8 update once every 1*9 seconds, Default is 

second, There are 5 commands associatea with the program 


C = display status of 16 channels 

P »= display status by process PID 

H = display help frame (timeouts after 1 min.) 
E = Exit to VMS DCL 

DigitCil=9) Change cycle time, 


key pad can also be used to enter commands, The special fumetion 


Keys on the VTI52 or VT192 correspond to the first 4 commands (3 on VT52), 


Typing ANY key will cause a display refresh, 


Include “LABCHNDEF,FOR® 


Characterald STATUS (4) 

Character*& XTIME 

Characterr? XDATE 

Parameter COMMAND MAX = 4 

Character*x] COMMAND, COMMAND, TABLE (COMMAND MAX,2) eESCAPE, TERMINATOR 
Craracter*x63 COMMAND DEV 


External SSS, NOTRAN,SS#, NORMAL, SSS,PARTESCAPE 
External IOSM,CVTLOW, LUSM,NOECHO, LOSM, TIMED, LOS, READVBLK, LO$M, PURGE 


Logical SUCCESS,SYStQ]Qw,SYSSASSIGN 

Integer CHANNEL, ,OISPLAY FLAG, ULOLOISPLAY,COMMAND CHAN 
Integer DEF TIME, OUT, TIME, OUT 

Byte ERASE SCREEN(2) HOME (2), ERASE LINE (2) ,¥TS2,MODE(7) 
Integere2 LO,STATUS(4) ,ChHAR COUNT 

Equivalence (ESCAPE, HOME), (CHAR, COUNT, JO, STATUS(2)) 


VT52 contro] ESCAPE Sequences 


Data HOME,ERASE SCREEN, ERASE LINE 
1 A7aa Oe He PSR Oe Se ORT KTS 


VT1I@@ control ESCAPE sequences 
This ESC seq places a VT102 in VTS2 mode 


Data VISA, MODES “3370, * (ee Pe er 1 550M 


Data STATUS/*®Unknown ",*Imactive’s” Active %,% °/ 
Data COMMAND, TABLES °C, OP, ES OHS OPO, Oy PSP, PROS 
Data DISPLAY FLAG, ERASE, FLAG /1,,TRUE,/ 

Data DEF, TIME, OUT /1/ 


Map to the GLOGAL DATA section created by the I/0 program 


Call LABIO,INITC) 


PROGRAM EXAMPLES 


1 Place VT19@°%s in VTS2 mode 


_ 


Type 528, VTS2, MODE 


Tnitialize Command input channel 

We will read the command via a GIOW with a 1 sec timeout 
Commands are single character, to simplify matters we will 
read with no echo and convert lower to upper case, 


— eo oe oon 


Call SYSSASSIGN( °TT*, COMMANDO CHAN,,,) 

GIO,READ = %Loc(IOSM,NOECHO) + ALocC(IOSM CVTLOW) + ZLocC(IOSM, TIMED) 
1 + &4Loc(IOS,READVBLK) 

TTZPURGE = %Loc(IOSM, PURGE) 

Go To 25 i Display Something 


Get a command from the user, but only wait a short time (TIME, OUT) 
sO we can update the screen, The input puffer is purged if a command 
wags decode on the last read, (Prevents unnecessary erase loops) 


PY o c= = 2 = 


r) DISPLAY, FLAG = OLD DISPLAY iDefault is last display 
TIME OUT = DEFL TIME, OUT IDefault time out 


21 TABLE, INDEX = 1 JAssume no escape sequence 


22 Call SYS$QIOW(,%Va) (COMMAND, CHAN) ,%Val (SIO, READ+PURGE) » 
1 IOLSTATUS +, %Ref (COMMAND) ,%Val (1) ,4Val (TIMEOUT) pone) 
PURGE = u 


i If escape seqe, set command table pointer to second table ana 
l get character following escape, 

TERMINATOR = Cnar( IO,STATUS(3) ) 

If( TERMINATOR ,yme. ESCAPE ) Go To 23 

TABLE, INDEX = 2 

Go To 2e !Get Char following escape 


23 If( CHAR COUNT ,ne, @) Then } Char count not # 
1 Check for char 1#9 
If( COMMAND ,ge, °@* .and, COMMAND ,Je, °9% ) Then 
DEF, TIME, OUT &= Tehar ( COMMAND ) @ Tchar( %@* ) 
1 Not 1*9 try a Command, 
Else 
ERASE FLAG = ,true, ! Screen erase 
Do 24 I & 1,COMMAND max 
I#¢ COMMAND ,ea, COMMAND, TARLECI, TABLE, INOEX)) GCISPLAY FLAG = I 
24 Continue 


End If 
PURGE = TTL PURGE }Purae the input buffer next time 
End If 
! 
1 Get date and time, then dispatch to gisplay routine 
1 
25 Call DATE (XDATE) 


Call TIME (XTIME) 


Go to (54-,6%,99,48) DISPLAY FLAG 
t 
1 Refresh the screen (Erase and Kedisplay) 
H 
38 DISPLAYLFLAG = OLD, DISALAY lReaisplay last diselay 
ERASE FLAG = ,true, 


PROGRAM EXAMPLES 


Go To 25 
t 
1 Dfieplay the HELP frame, set the temporary timewout to 1 minute 
{ 


4a Type 600, HOME,ERASE, SCREEN IDisplay the help frame 
TIMEOUT = 63 IGive the user 1 minute to reed it 
DISPLAY FLAG = OLOLOISPLAY IWhen it times out, defeult old 
ERASE, FLAG = ,true, 
Go To 21 


I 
l Generate the Status Line for each A/D channel 


52 Tf ( ERASE,FLAG ) Type 300, HOME,ERASE,SCREEN 

Type 108, HOME,XTIME,XDATE 

CHANNEL, COUNT & @ 

Do 51 CHANNEL @ 1,MAX AD CHANNEL 

T#( AD,BLOCK(2,CHANNEL) ne. @) Then lI1f allocated, display {nfo 
Type 20@,CHANNEL, STATUSCAD,BLOCKC1,CHANNELJ 41)¢ 

1 CAD, BLOCK(JeCHANNEL)» J = 2,6 ) 
CHANNEL COUNT 2 CHANNEL COUNT + 1 


Else {If mot allocated, say so 
Type 920, CHANNEL: *<Unused>*, ERASE, LINE 
End If 
51 Continue 


PID, COUNT # @ 
Do 52 PID, INOEX = 1, MAX,PID 

PID = CONNECT, BLOCK(PID, INDEX, 1) 

If € PID yne, @ ) PID,COUNT = PIO,COUNT + 1 
52 Continue 


Type 40@,ERASE, LINE, PID, COUNT, CHANNEL, COUNT 
OLD, OITSPLAY = DISPLAY,FLAG 

ERASE, FLAG = ,false, 

Go to 20 


i 
i Stetus display vie process (PID) 
{ 


60 If ( ERASE,FLAG ) Type 300, HOME, ERASE, SCREEN 
Type 182, HOME,XTIME,XDATE 
PID, COUNT @ g | Number of connected processess 
CHANNEL, COUNT = @ } Number of allocated channels 


Do 61 PID,INDEX = 1, MAX,PID 
PID # CONNECT BLOCK(PIOLINDEX,1) 
If ¢( PID «mee @ ) Then 
PIO,COUNT = PID COUNT + 1 
OLD, COUNTY @ CHANNEL, COUNT 
Do 62 CHANNEL = 1, MAX AD CHANNEL 
Tf€ AD,BLOCK( 2,CHANNEL) ea, PID ) Then JIf right PIO, display into 
Type 202, CHANNEL, STATUSCAD SLOCK(1,CHANNELI 41), 
1 CAD, BLOCK(J,CHANNEL), J = 2,6 ) 
CHANNEL, COUNT = CHANNEL,COUNT + 1 


End IF 
62 Continue 
Tf COLD, COUNT eq, CHANNEL COUNT ) Type 80, °<None>’,PID, ERASE, LINE 
End IF 
61 Continue 


Type 40¢,ERASE,LINE-PID COUNT, CHANNEL COUNT, ERASE SCREEN 
OLD,DISPLAY = DISPLAY,FLAG 

ERASE,FLAG = ,false, 

Go to ev 
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I 
1 Exit 
! 


99 Call Exit 
H 


1 Format Statments 
i 


14¢ FormatCix,2al,” Lab I0 Status as of %,A," °,A// 
1° Channel Status PID Tics/Sample Bufter Size 
1 Buffers °%/) 
228 Format(15,5x,A8,Z210,4112) 
3298 Format(’ %,4A1) 
4B@ Format(’ *"2A1/*% Totals: °%,12-" Processes connected “,Tl2," Channel 
1 allocated’/’ <Type an H for help>’2Ais) 
See Format(’ ’7A1) 
608 Format(’ "4Als 
1° The following commands are availatle:’// 
1’ VT14@ VTS2 any’/ 
1° weenwea avnea weal / 
1° PFI red Cc Channel Gisplay’/ 
1° PFe2 blue P Process Display’/ 
1° PF grey H Help Gisrlay’/ 
1° PFY4 n/a — Exdt’s/ 
1° To change display time, tyre a digit d=-9 for the desireq time’// 
708 Format(A) 
82a Format’ “pA6elixX,Z1de2Al) 
980 Format(15,5x-48,241) 
End 


tlEnd of File) 


IFite: LABIOPEAK,FOR 


Program LABIOL PEAK 
{ This routine continuously samples channel #1 search for peaks, 
{ Tre sample pate is 1/TIC. It reports the PELK height and position 
lL to logical channel “LASTO, PEAK DATA? 


Incluge “LASCHNDEF, FOR? 


Parameter MBX NAME = “LARIO PEAKS 
Characterx13”4 RETURN 

Character*x15 COMMAND 

Characterx24d DATE, TIME 

Logical*d SUCCESS,SYS#CREMBX 


Parameter AD CHANNEL = 1 L Channel Number 


PROGRAM EXAMPLES 
Parameter AD,RATE = 1 ! Rate 
Parameter AD BUF SIZE = 512 | Buffer Size 
Parameter MAX PEAKS = 19 
Integere4 ITABLECL@),INLAST, INPTR, OUTPUT (2,MAX PEAKS), IDIMO,NPEAKS 
Imtegera2 INPUTCAD BUF SIZEx2) 


Data ITTABLE/1Gxa/ 
Data INLAST,INPTR, IDIMO,NPEAKS/&,@,MAX, PEAKS, B/ 


Map To the Global Data Base and the event fiags 

Call LABIO,INIT(@) 
Open Mailbox to LABIO, CONNECT 

Open ( Umit = 1, Name = “LABIO, CONNECT’ » Type = *OLD’ ) 
Create Mailbox for response from LABIO CONNECT 


SUCCESS = SYSSCREMBAX(,4BX CHANNELS, ,%Val (°FDAR® x) ep MBX, NAME) 
Tf Camot, SUCCESS ) Call FATAL ,ERROR( SUCCESS, *°CREATING MAILBOX*%) 


Open via FORTRAN 

Open ( Unit = 2, Name = MBX, NAME, Type = “OLD" ) 
Deassign the channel assigned when we created it 

Cali SYSSDASSGN( 4Val(MBX CHANNEL) ) 
Open A Data File 

Open( Unit = 3, Name = *LABIO PEAK DATA’ ,»Type = "NEW? ) 
Connect to the LABIO system 


COMMAND = “CONNECT? 
Weite(1,190) COMMAND, Max NAME 


Walt for Response from LABIG system 


Read(2,200) RETURN, CODE,RETURN 
If( RETURN CODE ,ne. #@ ) Go To 99 IFailed to connect! 


Allocate Channel AD, CHANNEL 
Rate = AD,RATE 
Buffer size = AD, BUF SIZE 


COMMAND = “ALLOCATE” 

Weqte (1,400) COMMAND, AD CHANNEL, AC RATE, AD BUF SIZE, 2 

Read(2,20%) RETURN, COGE,RETURY 

If( RETURN, CODE ,yne, 8 ) Go To 99 [Failed to allocatel 
Enable data acqusition by setting event flag ACTIVITY and NOTIFY 


Cell SYSSSETEFCAValCEF ACTIVITY, GF F+40, CHANNEL) ) 
Call SYSSSETEFCZValCEF NOTIFY, OF Ft AD CHANNEL) ) 


Now, wait for buffer to be filled, event flag STATUS will be set 


PROGRAM EXAMPLES 


i when data are ready 
5 Call SYSSWAITFR( AValCEF STATUS OF F+AD, CHANNEL) ) 


1 Buffer is filled, get the buffer index 
{ 
INDEX = AD, BLOCK(7,/AD CHANNEL) 


{ Move data from data buffer to peak processing buffer 


De 10 I = 1, AD BUF,SIZE 
10 INPUTCI#INLAST) © DATA, BUFFER(I, INDEX, AD, CHANNEL ) 
INLAST = INLAST + AD, BUF,SIZE 


i Clear the STATUS event flag and notify the I/0 process 
j 


Call SYSSCLREF( 4Val(EF STATUS OF F+AG CHANNEL) ) 
ICDEBUG) only 
i Write (37682) (DATA, BUFFER(CI, INDEX, AC, CHANNEL), 151,40, BUF SIZE) 
i 
Call the peak orocessing routine 
H 
1S Call PEAKCITABLE, INPUT, INLAST, INPTR,QUTPUT, MAX PEAKS, NPEAKS) 


i Report the peak info 
PEAK, SWITCH = NPEAKS !Remember the peak switch 
If( NPEAKS ,me, 4 ) Then iwWe have some peaks 
1#( NPEAKS olt,. @ ) NPEAKS = MAX, PEAKS !WE have the max 


Do 2@ I] = 1, NPEAKS 
TOTAL, PEAKS = TOTAL, PEAKS + 1 !0ne more 


2u Wefte (3,54) TOTAL,PEAKS,COUTPUT(J,I)- J = 172) 
End I¢ 
NPEAKS = A tReset the pointer 


Tf#€ PEAK SWITCH ,1t, #@ ) Go To 15 IMore peaks to find 
! Move any unprocessed data to the beginning of the input array 


If ( CINPTR ,gt, @) gand, (INPTR ,I1t, INLAST) ) Then 
Do 34 IT = te INLAST=INPTR 


30 INPUTCI) = INPUTC INPTReI] ) {Mave the data 
INLAST = I [Last element stored 
Else 
INLAST = 4% 
End If 
INPTR = ¢ [Last element processed 


1! Go wait for more data 
Go To § 


£ All dome, Call the exit routine 


99 Call EXIT¢1) LExit 
1g0 Format(*® %24,4) 

20a Format(I2,4) 

40d Format(*® %24,41) 


PROGRAM EXAMPLES 
500 Format( 3118) 
680 Format(15) 
End 
IlEnd of File) 


1File PEAK,FOR 


Subroutine PEAK(CITABLE, INPUT, INLAST,INPTR,OUTPUT, IDIMO,NPEAKS) 
LA triviel peak=picking routine, The calling sequence {is patterned 
tafter the LSPLIB routine PEAK, 


Integer*4 ITABLEC1@),QUTPUTC2,IDIMO),INLAST,INPTR, IDIM@,NPEAK 
Integer*2 INPUT(1) 
Parameter NOISE a 5 {No{se value = 5 A/D units 


Initialize some parameters, if necessary 
If#( NPEAKS ,)t, 38 ) NPEAKS = @ 
Tf€( INPTR ,)t,. @) INPTR = 


tFiret time thru? 
I#¢ 


INPTR lt, INLAST ,amd, ITABLEC1) ~ea, O ) Then 
INPTR c INPTR + 1 
ITABLEC1) =& 1 {Assume we're pising 
ITABLE(2) = 1 ttirst pofnt 
ITABLE(C3) & INPUTCINPTR) 
End If 


tAny data to process? 
TfCINPTR it. INLAST ) Then 
Do 18 I w INPTR+i, INLAST 
If( ITABLEC1) «gt. @) Then ‘we're risings look for a fall 
T#¢ INPUTCI) lt. ITABLEC3)*NOISE ) Then tWe found a peak 
If( NPEAKS ,}t.e IDIMO ) Then lAny room to store it? 
NPEAKS @ NPEAKS + | 
OUTPUTCI,NPEAKS) = ITABLEC3) 
OUTPUTC2,NPEAKS) = ITAGLE(2) 
ITABLEC1) = #1 
Else tNo, tell user 
INPTR = I = | 
NPEAKS = e[DIMO 
Return 
End If 
End If 
Else lwe’re falling, see if we found a valley 
T#€ INPUTCT) ,gte ITABLE(S)¢NQISE ) ITABLE(1) = 1 
End lf 
TTABLE(3) = INPUT(T1) 
128 ITABLE(2) = ITABLEC2) + 1 
End If 


INPTR = ~1 lNormal exjt all data processed, 
Return 


End 


PROGRAM EXAMPLES 


{Filet LABIOSAMP,FOR 
Program LABIO, SAMPLE 


This program samples channel #2 once every 12 seconds, 

It acquires 1@ points at i/tic,s, averages them and than 
Reports the date, timer, and average value on logceial device 
LABIO, SAMPLE, DATA 


Include "°LABCHNDEF,FOR? 

Parameter MBX, NAME = “LABIO,SAMPLE“ 

Character#13Q RETURN 

Character*iS COMMAND 

Character*x24 DATE, TIME 

Logi¢cal*4 SUCCESS, SYSSCREMBX 

Integere4 DELTA, TIME (C2), NEXT LTIMEC 2) 

Integer«4 AVERAGE 

Parameter AU CHANNEL = 2 1 Channel 
Parameter AD ,RATE = | ! 
Parameter AD BUF SIZE = lv 

Parameter SAMPLE,RATE = °O BeHT1h? 

Parameter MAX SAMPLE = 1e@ on i Maximum # samples 


{ Map To the Global Data Sase and the event fiags 


Call LABIOLINIT(2) 
| Open Mailbox to LABIO CONNECT 

Open ( Unit = 1, Name = “LABIO,CONNECT* » Type = *OLD* ) 
1 Create Mailbox for response from LABIO, CONNECT 


SUCCESS = SYSSCREMBX(C,MBX CHANNEL pep RVA8IlC TF DOO x) ps MBX NAME) 
If Cemot, SUCCESS ) Call FATAL,ERROR( SUCCESS, “CREATING MAILBOX’) 


1 Open via FORTRAN 
Open ( Unit = 2, Name = MBX NAME, Type = *Old" ) 
} Deassigm the channel assigned when we created it 
Call SYSSDASSGN( ZVal (MBX CHANNEL) } 
1 Open A Data File 
Open( Unit = 3, Name = “LAB, SAMPLE DATA", Type = ‘New’ ) 
} Connect to the LABIO system 


COMMAND = "CONNECT? 
write(i,140) COMMAND, MBX NOME 


§ Wait for Response from LAsIG system 
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Read(2,200@) RETURN, CODE,RETURN 
Tf( RETURN, CODE ,ne. 2) Go To 99 {Failed to connect! 


Allocate Channe) AD CHANNEL 
Rate = AD,RATE 
Buffer size = AOD BUF SIZE 
Collect 1 buffer at a time 


COMMAND = “ALLOCATE? 
Write(1,420) COMMAND, AD CHANNEL, AD RATE, AD, BUFLSIZE, 1 
If( RETURN CODE ,ne, @ ) Go To 99 tFailed to allocates 


L Every SAMPLE,RATE secs, we will collect one buffer of data 


1 Convert ASCII delta time to binary 
Call SYSSBINTIM( SAMPLE,RATE, DELTA,TIME ) 


| Schedule wakewups every delt time interval 
1 But first cancel any previous wakeups 
Call SYSSCANWAK(,) 
Call SYSSSCHDWK(,, DELTA, TIME, DELTA, TIME) 


1 Walt for scheduled time interval 
12 Call SYS$HIBER() 


| Enable data acaysition by setting event tlag ACTIVITY and NOTIFY 
j 


Call SYSSSETEFC4ValCEF ACTIVITY GFF +40, CHANNEL) ) 
Call SYSSSETEFC4ValCEF NOTIFY, OFF +AD, CHANNEL) ) 
Call SYSSASCTIM(, DATE, TIME, ,) 


! Now, wait for buffer to be filled, event flag STATUS will be set 
lL when data are ready 
Call SYSSWAITFR( “4ValCEF, STATUS OF Ft AD CHANNEL) } 


} Butter 18 filleds get the nuffer index 
INDEX = AGZBLOCK(7s AD, CHANNEL) 


i Clear the STATUS event flag ana notify the I/D process 
Call SYSSCLREFC “Val(EF, STATUS OFFAL CHANNEL) ) 
Call SYS#SETEF( *4Val(EF NOTIFY, ,OFF+AD CmANNEL) ) 

{ Average the points 
AVERAGE = @ 
Do 26 1 = i, AD BUF SIZE 

20 AVERAGE & AVERAGE + DATA, HUFFER(C I, INDEX,AD, CHANNEL) 
AVERAGE = AVERAGE/AD, BUF, SIZE 


lL write out average with the aca, date/time 
weite(3,408) DATE, TIME, AVERAGE 


l If we’re all dome, close files and exit 
If( AD, BLOCK (6, AD CHANNEL) ,)t. MAX, SAMPLE ) Go To 12 


1 All dome, Call the exit routine 


99 Call EXIT(4) sExwit 
120 Format(’ *,A,A) 


PROGRAM EXAMPLES 


220 Format(l2,A4) 
408 Format(’ °,A,41) 
End 


{(End of File] 


tFiles TESTLABIU,FOR 


H 
i 


i 
I 
t 


18 


Tests the LABIO system by allocating upto 16 channeis 
Enter the mumber of channels, rater and buffer size 


Program TEST ,LABIO 
Include “LABCHNDEF,FOR’ 
Parameter MBX NAME = “TEST LABIO?’ 
Characterx13@ RETURN 
Character*iS COMMAND 
Characterwx2d DATE, TIME 
Legical*4 SUCCESS,SYSSCREMBX 
Integer*4 TEST CHAN, TEST RATE, TEST SUF SIZE 
Map To the Global Data Base and the event flags 
Call LABIOLINIT( 4a) 
Open Mailbox to LABIO CONNECT 
Open ( Unit = 1, Name = “LABIO,CONNECT® , Type = “OLO* ) 


Create Mailbox for response from LABIO CONNECT 


SUCCESS = SYSSCREMBX(,4AX CHANNEL yop XV al (°F DG8% x) ep MBX NAME) 
lf (note SUCCESS ) Call FATAL,ERROR( SUCCESS, “CREATING MAILBOX’: 


Open via FORTRAN 

Opem ( Unit = @, Name = MBX NAME, Type = “OLD® ) 
Deassign the channel assiaqned when we created it 

Call SYSSDASSGN( 4val(4BX CHANNEL) ) 
Connect to the LAGIC system 


COMMAND = *CONNECT? 
wedte(i,164d) COMMAND, MAX NAME 


Wait for Response from LABIO system 


Read(2rcdv) RETURN, CODE,RETURN 
If#f( RETURN,CUDE ne, 4 ) Go To 99 lFailed to connecti 


Get parameters from onerator 


LAST, TEST, CHANSTEST, CHAN 
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Type 600,° Enter mumber of channels, rateCtin tics), and buffer size‘ 
Accept 700, TEST, CHAN, TEST, RATE, TEST BUF SIZE 
If ( TEST CHAN ,eq, @ ) CAI) Exitct) 

| 

i Deallocate Channels from last time 


Do 20 AD, CHANNEL=1,LAST,TEST,CHAN 


Call SYSSCLREFCAValCEF ACTIVITY OFFtAD CHANNEL)) Stop Acge 
Call SYSSSETEFCAValCEF NOTIFY OFF HAD CHANNEL) ) 


COMMAND = *DEALLOCATE? 

Weite(1,40@) COMMAND, AD CHANNEL 

Read(2,200) RETURN CODE,RETURN 

If( RETURN,CODE ,ne, @ ) 

1 Type SAM, * Deallocation failure’ ,RETURN,CODE,RETURN 
ea Continue 


1 Allocate Channels 
Do 30 AD, CHANNELE1, TEST CHAN 


COMMAND = "ALLOCATE? 

Wedte(l,40@) COMMAND, AD CHANNEL, TEST, RATE, TEST BUF, SIZE,@ 
Read(2,2d0) RETURN, CODE,RETURN 

If#f€ RETURN CODE ,ne, @ ) 

1 Type 548, ° Allocation failure’, RETURN CODE,RETURN 


! Enable data acausitjon by setting event flaaq ACTIVITY and NOTIFY 
{ 


Call SYSSSETEFC%Val (EF ACTIVITY, OF F+AD, CHANNEL) ) 
30 Call SYSSSETEFCAValCEF NOTIFY OF F+AD CHANNEL) ) 
Go To 18 
| 
l Connect Failure 
I 


99 Type 580, % Connect failure’, RETURN, CODE,RETURN 
Go To 10 

1228 Format(’ *,A,A) 

202 Format(I2,A) 

4av Format(*’ °,A,4T) 

5a0 Format(A/* *°,12,4) 

600 Format(A) 

788 Format(311@) 
End 


lFile: LABIOCOM,FOR 
Logical Function LABIULINII( PRIVILEGE ) 


This routime is used to attach a LAS1O user program to the 
LABIO system, It associated the two event flag clusters and 
maps to the LABIO global) data section, 


— 2 on Oe 


INPUTS PRIVILEGE » Privileged LABIOQ users can set this 


— = B= 2= = 2= O= on 


— on on oe 


ee ee me Oe ee Oe 
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to 1 to allow write access to the data base, 
All others must set this to #@, 


OUTPUT? None = Currently wil) always return with success code, 
If an error occurs, FATALERR {8 called to display 
the error messages and STOP THE PROCESS} 


Include “LASCHNDEF,FOR® 
Logical*4 SYSSASCEFC,SYSSMGALSC,SUCCESS,SYSSWAITFR 
External SECSM WRT 


Create event flag cluster EF,NOTIFY and associate with event flags 64=95 
These are used to notify the Data Acouisition poracess, 


SUCCESS = SYSSASCEFC( &VALCEF NOTIFY, 1),EF NOTIFY ,CLSTRe,) 
If € ,not,. SUCCESS) 
1 Call FATAL,ERROR( SUCCESS, “CREATING EVENT FLAG CLUSTER®) 


Create event flag cluster EF, STATUS and associate with event flags 96=12 
These are used to notify and report the status of the user buffers 


SUCCESS = SYSSASCEFC( X%VALCEF, STATUS 1), EF,STATUS,CLSTRy») 


If ¢€ ~mot, SUCCESS) 
1 Call FATALLERSOR( SUCCESS, “CREATING EVENT FLAG CLUSTER’) 


Map to the GLOBAL DATA section created by the I/0 crogqram 
Wait for event flag EF, CONNECT (nonsecrivileged) or 
EF, DATA,ACQ (erivileged) before attempting mapping, 


SECTION(1) = Z%Loc(LABIO, BUFFERS) 
SECTION(2) = XLoc(LAAIO, SUFFER,E) = 1 


SECTION, FLAGS = @ iPefault flags 
If( PRIVILEGE ,ne, @ ) Then 
SECTION, FLAGS=%Loc(SECEM WRT) 
Call SYSSWAITFR( &Val€ EF, OATA,ACG ) ) 
Else 
Call SYSHWAITFR( 2ValC EF,CONNECT ) ) 
End If 


SUCCESS = SYS&MGSLSC( SECTION,«,%Val (SECTION, FLAGS), "LABIOCOMMON?,, 
Tf( emot, SUCCESS ) Call FATAL, ERROR(SUCCESS, ’mapoing data sectian’ 


LABIO, INIT = SUCCESS 
Return 


End 
FATAL,ERROR = FATAL ERROR HANDLER 


This routine is used to report a fatal error and exit the tmage 


INPUT: ERROR, CODE = SYSTEM ERROR CODE TO REPORT 
ERROR, MESSAGE « ERROR MESSAGE TO BE PRINTED 


OUTPUTS’ NONE 


7-38 


o— OO 8 C= Oe 2 Om Be 8 OO 


-_ 


| 
1 Print 
1 
| 
{ Print 
{ 


12u 
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>>>> THIS ROUTINE DOES NOT RETURN <eccc 
FUNCTIONS TYPES the message 
"process name=FATAL ERROR = error, message’ 


Then prints system message corresponding to ERROR, CODE 


Finallys exits image by calling LIBSSTOF 
Subroutine FATAL ,ERRORCerror, code,error, message) 


Integera4 ERROR, CODE 

Character ERROR MESSAGER(«) 

Logical*4d SUCCESS,SYSECREMBX,SYS#GETJPI 
Integerx2 JP12(8),PROCESS NAME LL 
Integer*4 JPI4(4) 

CharactereiS PROCESS NAME 

Equivalence (JPI2,JP14) 

Parameter JPIS ,PRONAME"°31C°X 


Get the process name 


JPT2(i) = 15 INumber of elements in name 
JPT2(2) = JPIS,PRCNAM \Want process name 

JPT4(2) = %Loe (PROCESS NAME) lAddress of process name 
JPI4(3) = &%Loc( PROCESS, NAME L) lAddress of process name length 
JPI4(4) = @ }Termimate list 


Call SYSSGETJPI (eee IPI4ese} 

the process name and error message 

Type 182, PROCESS, NAME(1SPROCESS NAME LL) ,ERROR, MESSAGE 
the error message corresponding to ERROR CODE and exit 
Call LIBSSTOPC %4Val (ERROR, CODE) ) 

Format(’ ’A,;*’ © FATAL ERROR %, A) 

Stop 


END 


$lEnd of File} 


tFiles 
{Define 


LABMBXDEF,FOR 

malibox olock for LAG, IC 

Parameter MAX, MESSAGE = 128 IMaximum message length 
Parameter MBX, RESPUNSE,L = 2 iResponse Length 


Parameter MAX, ,ACK,L = MAX, MESSAGE +MEX RESPONSE LL 


Integerxd MBX, TOLSTATUS, MBX MESSAGE L 


tFiles 
t 
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Integer*4 MBX PID 
Byte MBX, RESPONSE (MBX, RESPONSE ,L) 
Byte MBX, MESSAGE (MAX MESSAGE) 


Common /MBXUBLOCK/ MEX CHANNEL, MBX, IO,STATUS, MBX MESSAGE L, 
{ MBX,PID, MBX,RESPONSE, MBX MESSAGE 


> MBX,BLOCK < 


(me aE CMANNEL OT ping aes 
TWORLMESSAGESL 1 MOXLIOLSTATUS 1 Word 304 
MOPED Wendl sal 
DT NaXGRESPONSE dd Kord 78 


! ! 


| i 
I MBX MESSAGE 1 Word GeMAX MESSAGE+8 
! ! 
4 ! 


LEnd of File} 


LABCHNOEF,FOR 


Implicit Integer (A=Z) 


JAD, CHANNEL STATUS BLOCK cefined the parameters associated 
twith each A/D channel 


i 


IFor each A/D channels 


! 1) 
i 2) 
! 3) 
i 4) 
i 5) 
} 6) 
1 7) 
! 

! 


8) 


Status of the channel (CACTIVE or INACTIVE) 

PIO of the connected orocess allocated the channel 

Ti¢cs/sample (time between sample in tics) 

Buffer size in words 

Buffer count (2 if no limit) 

Buffers acquired 

Index to the last full puffer containing valid data 
¥@s> No buffer avatlaole 

Number of data points in the last full buffer 


The following elements are used by the gata acquisition interruct service 
routine, In general, they wil! not be used py an application process, 


| 

i 

t 

+ 9) 
1 1@) 
' ii) 
1 12) 
1 


Index to the current data acauisition buffer 

Number of data points im the current data acquisition buffer 
Number of tics until the next sample 

Gffset to the next data noint to ne acquired (wrst buffer 41) 
(NOTE: Offset = Index = 1 ) 


Parameter MAX AD CHANNEL = 16 lMaximum mumber of channels 
Parameter MAX SUF SIZE = Si2 IMaximum buffer size 
Parameter INACTIVE = } I35tatus values for AD, BLOCK 


i} 
i 
t 
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Parameter ACTIVE = 2 i 


Integer*4 AD BLOCK (MAX AD, CHANNEL, 16) 


Date buffers 
Parameter BUFFER, COUNT = 2 } Number of buffers/channel 


Integer*2 DATA, BUFFER(MAX BUF SIZE, BUFFER, COUNT, MAX, AD CHANNEL) 


iThis module defines the common data structures 
tfop the privileged LABIO processes, 


{CONNECT BLOCK used to identify processes currently 
tconnected to the LAGIO process, 


j 
i each process CONNECT, BLOCK contains: 


! 
t 
{ 
i 
I 


Proceas ID (PID) 
Internal VMS I/0 channel of the connected processes mailbox 


Parameter MAX,PID = 16 IMaximum number of processes 
Integers4 CONNECT BLOCK (MAX, PID, 2) 


DATA COMMON SECTION 
This will be mapped as a global data section 


Common /LABIO,SECTION/ AD, BLOCK, DATA, BUFFER, CONNECT, BLOCK 

Common /LABIO,SECTION/ LABIO,BUFFERLE lLast element of DATA section 
Equivalence (AD ,BLOCK,LABIO,BUFFER,S) iFirst element of DATA section 
Integers4 SECTION(2),SECTION SIZE 


Define Global Event Flag Cluster mames and numbers 


EF,NOTIFY,CLUSTER is used to motify the oriveleged LABIO process 
that change of status has occured, i,@. channel has 

become ACTIVE or INACTIVE, or @ buffer has been freed, 

Fiags 0°15 of the cluster correspond to CHANNELS 1816 

Flags 16°31 are not used, 


Parameter EF,NOTIFY,CLSTR = “LABIO,EF, NOTIFY? 
Firat fleg of notify 
Parameter EF ,NOTIFY,1 = 64° 
Offset to Notify 
Parameter EFLNOTIFY,OFF = 63 
Event Flag EF,DATA,ACQ is set when LABIO, DATA, ACG has completed initialization 
Parameter EF, DATA, ACQ = EF,NOTIFY ,1+17 
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tL Event Flag EF, CONNECT is set when LABIO,CONNECT has completed initialization 
Parameter EF_CONNECT = EFL,NOTIFY 1418 


EF,STATUS {8 used to notify a applications process 
that e buffer is available, and used by an application 
process to inicate the status (ACTIVE or INACTIVE) of 
a channel, 


Flags 6915 of the cluster are the ACTIVITY flags 

{f set (by the application process), the corresponding 
channel(1"16) is active, If clears the channel is inactive, 
When a change of atate {a made the corresponding flag must 
also be set in Cluster EF NOTIFY CLUSTER, 


Fleges 16°31 are the buffer status flags, when set, 

a buffer for the corresponding channel (116) is available, 

The application process mus clear the flag and set the corresponding 
flag in EFLNOTIFY, CLUSTER when it is finished with the buffer, 


en = 8 = 0 8 Om On Om Om OO = oe O- 


Parameter EF,STATUS ,CLSTR = “LABIO,EF STATUS? 
IFipst event flag in Activity and Status 

Parameter EFLACTIVITY,1 3 96 

Parameter EF, STATUS,1 © EF,ACTIVITY,1 + 16 
LOffset to Activity end Stetus 

Parameter EFL,ACTIVITY, OFF & 95 

Parameter EF.STATUS, OFF w EF ,ACTIVITY,OFF + 16 


1 BIT array, BITCI) = has bit I set ( I 2 1 to 32 ) 


Integer*4 BIT(32) 

Data BITS 91°X, 7 27K, 94K, PBK, PLO Ky 9 2B7K, PUNK, BOX, 
#1DO°Xs ©2AB°Xs UOO Xs, “BOO°Xe "1 B00°X, *2080°X, 
"UABO°X, "BOSA°XK, °1LOUGB"X, "20000°X, °"4OBA0"X, 
"BOARO°X, “1AGORA'N, 2UAHGR°X, "4O0Q00°X, 
"BOB0A0°K,*1000GR0°X, “2Q0R000°X, °4R00000'°X, 
*BO00000°X, *10000000°X, °20000000°X, "4Qg0ane0"X, 
"80000000"X/ 


> Oe oe ee ee 


j 
iCEnd of File) 


IFile: LABIOSEC,FOR 

| Block Data Routine to place the LABIO,SECTION Common 
tl on a page boundary, This is necessary because we wil! 
tl pemap it, We could heve used a MACRO program to 

| declare the PSECT LABIO,SECTION to be paged aligned, 
t byt the LINKer would then give us a warning message, 


Block Date LABIO,SECTION 
Common /LABIO,SECTION/S AD, BLOCK 
End 


I 
tlEnd of File) 
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SFILEsCONNECT,CO™ 


i This command file loads the connectetoei{nterrupt handler (CONINTERR) and 


tL then connects the KWil#K to to it. 
4 

$ R SYSSSYSTEM:ISYSGEN 

LOAD CONINTERR 


CONNECT KWA® /ADAPTERS3/CSREXO7T7U444/VECZ%0GB4/0RIVERSCONINTERR 


$ Exit 


{Files LABIOSTRT,COM 
t 


ISterts up the LABIO SYSTEM 


Runs the data acquisition process and connect process 
las detached tasks, Then runs the status program, 
4 


IMake the logical name assignments 
SAssign/Group LABIO,LOG LABIO,LOG 
SAssign/Group LABIO.DAT LABIO, SEC, FILE 
SAssign/Group KWAUS LABIO,AD 

$Set Noon 

$ 

S}Run the data acquisition orogram 

$ 


SRun/Uies *FSUSER() %= 
/AstaLimita 228 
7Output s LABIOACG,DAT= 
/Prioritys i7= 

/Process names LABIO,DATA,ACQe 
/Privilegess SAME= 

LABIOACO 

$ 


$iRun the connect program 
$ 


$ RUN/U{ece "FSUSER()%= 
/Outputs LABIOCON,DATe 
/Prioritys 15@ 
“Privileges SAMEe 
/Process,names LABIO, CONNECT 
cenetD oul 


$iRunm the status program 
$Run LABIOSTAT 
$Set On 


{Files LABIOCOMP,COM 


tlLog file 

IGlobal Section File 
IConnectstorInterupt device is KWell 
tDon’t abort if we can’t run @ program 
lIt {8s probably elready running! 


tRun as a deatched process 
lWe need a large AST quote 
ISYSSOUTPUT 
tHigh, Real=Time 
lName of Process 
\Same privileges 
lImage to pun 


priority 


{Run as a detached process 
ISYSSOUTPUT 
iGive it a high but not mighty priority 


IName of the process 


| Command procedure to compile and assemble 


1 the modules of the LASIO system, 


BAA 


Mecro/Liaet GBLSECUFO 


Fortran LABIOACG,LABIOCON,LABIOSTAT,LABIOCOM,LABIOSEC 
Macro/Liat LABIOCINeSys$Library:LIB,MLB/Library 


PROGRAM EXAMPLES 


$i Demo Programs 
$ Fortran LABIOSAMP,_LABIOPEAK,PEAK,TESTLAGIO 


Files LABIOLINK,COM 

1 Command procedure to LINK the LABIO system 

B Link/Map LABIOACQ,GELSECUFO,LASIOCOM,LABIOCIN/Option 
$ Link/Map LABIOCON,LABIO/Option 

8 Link/Map LABIOSTAT,LABIO/Option 

$} Demo Programs 

$ Link/Map LABIOPEAK,PEAK,LABIO/CRrt 

$ Link/Map LABIOSAMP,LABIO/Opt 

B Link/Map TESTLABIO,;LABIO/OPt 


lFijles LABIO,OPT 

lLinker OPTION file for linking any process to be ysea with LABIO 
LABIOCOM 

Cluster = LABIO,CLUSTER,,,LASBIOSEC 


{Files LABIOCIN,OPT 
tLinker OPTION file for linking LABIG,DATA,ACQ 
Cluster = Labio,cluster,,,Labiocin 


PROGRAM EXAMPLES 


7.2 AIRLINE RESERVATION SYSTEM 


This example shows a series of programs to make and cancel airline 
reservations. This is not a "real-time" example in the same sense as 
the data acquisition and manipulation example in Section 7.1. 
However, the airline reservation system does show a shareable image 
data base, access to which is synchronized by the use of common’ event 
flags. It also shows the use of a shared memory common event flag 
cluster. 


The following commands define the logical names and install the global 
section for the airline reservation system (FORTRAN program examples). 
The shared memory is named SHM. 


S$ COPY DATABASE.EXE SYSSSHARE:DATABASE.EXE !PUT IT IN LIBRARY 

$ DEFINE GBLSDATABASE SHM:DATABASE !LOGICAL NAME DEF. FOR SECTION 
$ RUN SYSSSYSTEM: INSTALL 

INSTALL> SYSSSHARE:DATABASE/OPEN/HEADER RESIDENT/SHARED 

INSTALL> [CTRL/Z] - 

S$ DEFINE/SYSTEM CEFSCEFN1] SHM:CEFN1 !LOG. NAME DEF. FOR CLUSTER 

$ RUN [desired program in the reservation system] 


AAANAAAAANNAANN 


a 


10 


900 
910 
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DATADESC, FOR 
VMS AIRLINE RESEVATION SYSTEM 


BEING A SIMPLE DEMONSTRATION OF THE USE OF A GLOBAL 
DATABASE AS A SHAREABLE IMAGE UNDER VAX/VMS, 


DISCLAIMER: THIS SOFTWARE IS FOR DEMONSTRATION PURPOSES 

tata ONLY. NO AIRLINE IS EXPECTED TO HONOUR THESE 
RESERVATIONS. FURTHER, IT IS INTENDED ONLY TO 
DEMONSTRATE SOME OF THE TECHNIQUES AVAILABLE 
WITH VAX/VMS AND VAX-11 FORTRAN. 


PARAMETER NDESTS = 4 

PARAMETER NDAYS = 3 

PARAMETER NSEATS = 10 

PARAMETER ITOTSEATS = NDESTS*NDAYS*NSEATS* 2 


CHARACTER DESTINS (NDESTS) *6,SEATS (NSEATS, 2,NDESTS ,NDAYS) * 20 
CHARACTER DAYS (NDAYS) *3 


INTEGER HOWPAID (ITOTSEATS) 


COMMON /FLIGHTDATA/SEATS, DAYS,DESTINS 
COMMON /PAIDDATA/HOWPAID 


BLOCK DATA DATABASE 

INCLUDE 'DATADESC. FOR’ 

DATA DESTINS/'BOSTON', 'SYDNEY', ‘LONDON’, 'MADRID'/ 
DATA DAYS/'MON', 'TUE', 'WED'/ 

DATA SEATS/ITOTSEATS*! '/ 


END 


SUBROUTINE LOCKFLIGHT(IDEST,IDAY) 
INCLUDE ‘DATADESC.FOR' 


EXTERNAL SS$_WASSET 
INTEGER PREVSTATE ,EVFLAG 
INTEGER SYSSSETEF,SYSSCLREF,SYSSASCEFC 


EVFLAG = 63 + NDAYS*(IDEST - 1) + IDAY 

IF ( .NOT. SYSSASCEFC ($VAL(EVFLAG) ,&8DESCR('FLIGHTLOCKS'),,)) GO TO 900 
PREVSTATE = SYSSSETEF (%VAL (EVFLAG) ) 

IF (PREVSTATE .£Q. %LOC(SS$_WASSET)) THEN 


GO TO 10 

ELSE 
IF ( .NOT. PREVSTATE) GO TO 900 
RETURN 

END IF 


ENTRY UNLOCKFLIGHT 

IF (.NOT. SYSSCLREF(%VAL(EVFLAG))) GO TO 900 
RETURN 

TYPE 910 

FORMAT(' **** EVENT FLAG SERVICE FAILURE ****') 
END 


1000 
1010 
1020 
1030 
1040 


1050 
1060 


10 


20 


40 


60 


80 


90 


1 
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PROGRAM DISPLAY 
INCLUDE 'DATADESC.FOR' 


CHARACTER DESTIN*6,DAY*3,HOMERASE*4,BLANKS*6 ,SMOKE*1] 
CHARACTER TIMEDELAY*13,TOPOFSCREEN*6 


INTEGER SYSSBINTIM,SYSSSETIMR,SYSSWAITER,SYSSCLREF, DELAY (2) 
BYTE CTLERASE (4) ,CTLTOS (4) 

EQUIVALENCE (HOMERASE,CTLERASE(1)), (TOPOFSCREEN,CTLTOS (1) ) 
DATA CTLERASE/'1B'X,'H','1B'X,'J'/,BLANKS/' '/ 

DATA TIMEDELAY/'0O 00:00:10.00'/ 

DATA CTLTOS/'1B'X,'Y','22'X,'20'X/ 

FORMAT(' Enter flight destination: ',$) 

FORMAT (A) 


FORMAT(' There are no flights to ',A) 
FORMAT(' On what day? ',$) 


FORMAT(' ',A,'DESTIN DAY SEAT PASSENGER NAME CREDIT 
1 CARD NO. (0 IF CASH)',/,' ------ --- crn erect r errr nnn 
t 
a ee ne ee 1/) 
FORMAT ('+',A,' ',A,'‘ ',A,12,' ',A,110,/) 
FORMAT(' ',A) 
TYPE 1000 


ACCEPT 1010, DESTIN 

DO 20 IDEST = 1,NDESTS 

IF (DESTIN(1:2) .EQ. DESTINS(IDEST) (1:2)) GO TO 40 
CONTINUE 


TYPE 1020, DESTIN 
GO TO 10 


TYPE 1030 

ACCEPT 1010, DAY 

DO 60 IDAY = 1,NDAYS 

IF (DAY({(1:2) .EQ. DAYS(IDAY) (1:2)) GO TO 80 


CONTINUE 
IF (DAY(1:3) .EQ. ‘ALL') THEN 
IDAY: = =i 
GO TO 80 
END IF 
GO To 40 
CONTINUE 
IF (IDEST .EQ. -1) THEN 
JDEST = 1 
KDEST = NDESTS 
ELSE 
JDEST = IDEST 
KDEST = IDEST 
END IF 
IF (IDAY .FQ. ~1) THEN 
JDAY = 1 
KDAY = NDAYS 
ELSE 


JDAY = IDAY 
KDAY = IDAY 


END IF 

TYPE 1040, HOMERASE 

LINES = 0 

DO 500 IDEST = JDEST,KDEST 
ILOOP = 0 


DO 400 IDAY = JDAY,KDAY 
JLOOP = 0 


DO 300 ISEAT = 1,2*NSEATS 
ILOOP = ILOOP + 1 

JLOOP = JLOOP + 1 

IF (ISEAT .LE. NSEATS) THEN 


SMOKE = ‘N' 

ISMOKE = 1 

JSEAT = ISEAT 
ELSE 

SMOKE = 'S! 

ISMOKE = 2 

JSEAT = ISEAT - NSEATS 
END IF 


LSEAT = ISEAT + (IDEST-1)*2*NSEATS + (IDAY-1) *NDESTS 
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IF (LINES) 100,100,99 


99 IF (ILOOP - 2) 100,120,140 
100 DESTIN = DESTINS (IDEST) 
GO TO 140 
120 DESTIN = BLANKS 
140 CONTINUE 


IF (LINES) 160,160,150 


150 IF (JLOOP - 2) 160, 180, 200 
160 DAY = DAYS (IDAY) 
GO TO 200 
180 DAY = BLANKS 
200 CONTINUE 
IF (SEATS (JSEAT,ISMOKE,IDEST,IDAY) (1:4) .EQ. " ') THEN 
IF (ISEAT .NE. 1) THEN 
GO TO 300 
END IF 
END IF 


TYPE 1050, DESTIN,DAY,SMOKE,ISEAT,SEATS (JSEAT, ISMOKE, IDEST, IDAY) , 
1 HOWPAID(LSEAT) 
LINES = LINES + 1 
IF (LINES .GE. 19) THEN 
TYPE 1060, TOPOFSCREEN 
LINES = 0 
END IF 
300 CONTINUE 
400 CONTINUE 
500 CONTINUE 


END 


PROGRAM RESERVATION 
INCLUDE 'DATADESC.FOR' 
CHARACTER DESTIN*6,DAY*3,SMOKE*3,PAYMENT*4 


1000 FORMAT(' Enter destination: ',$) 

1010 FORMAT (A) 

1020 FORMAT(' There are no flights to ',A) 

1030 FORMAT(' On what day? ',$) 

1040 FORMAT(' Do you want a smoking area seat? ',$) 

1050 FORMAT(' The flight to ',A,’ is full on ',A) 

1060 FORMAT(" No smoker seats left. Is non-smoking acceptible ?',$) 
1070 FORMAT(' Non-smoking is full. Is smoking area acceptible ?',$) 
1080 FORMAT(' Your seat is number ',14,' on the ',A,' flight next ',A) 
1090 FORMAT(' Enter passenger name: ',$) 

1100 FORMAT(' Payment by cash or credit card? ',$) 

1110 FORMAT(' Enter credit card number: ',S$) 

1120 FORMAT (110) 

1130 FORMAT(' *** INVALID CREDIT CARD NUMBER ***') 


10 TYPE 1000 
ACCEPT 1010, DESTIN 
DO 20 IDEST = 1,NDESTS 
IF (DESTIN(1:2) .EQ. DESTINS(IDEST) (1:2)) THEN 
GO TO 40 
END IF 
20 CONTINUE 


TYPE 1020, DESTIN 
GO To 10 


40 


60 


80 


100 
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TYPE 1030 

ACCEPT 1010, DAY 

DO 60 IDAY = 1,NDAYS 

IF (DAY(1:2) .EQ. DAYS{(IDAY) (1:2)) THEN 
GO TO 80 

END IF 

CONTINUE 

GO TO 40 


TYPE 1040 
ACCEPT 1010, SMOKE 
IF (SMOKE(1:1) .EQ. '¥") THEN 


ISMOKE = 1 
ELSE IF (SMOKE(1:1) .EQ. 'N') THEN 
ISMOKE = 0 
ELSE 
GO TO 80 


END IF 
CALL LOCKFLIGHT (IDEST,IDAY) 


DO 100 ISEAT = 1,NSEATS 


IF (SEATS (ISEAT, ISMOKE+1,IDEST,IDAY) (1:4) .EQ. ' ') THEN 
GO TO 200 

END IF 

CONTINUE 


JSMOKE = ISMOKE .XOR. 1 
DO 110 ISEAT = 1,NSEATS 


IF (SEATS (ISEAT, JSMOKE+1,IDFST,IDAY) (1:4) .EQ. ' ') THEN 
GO TO 150 

END IF 

CONTINUE 


TYPE 1050, DESTINS (IDEST) , DAYS (IDAY) 
CALL UNLOCKFLIGHT 
GO TO 900 


IF (ISMOKE .EQ. 1) THEN 
TYPE 1060 
GO TO 170 

ELSE 
TYPE 1070 

END IF 

ACCEPT 1010, SMOKE 

IF (SMOKE(1:1) .EQ. ‘N')} THEN 
GO TO 120 

END IF 

ISMOKE = JSMOKE 


JSEAT = ISEAT + (NSEATS*ISMOKE) 
KSEAT = JSEAT + (IDEST-1)*2*NSEATS + (IDAY-1)*NDESTS 
TYPE 1080, JSEAT,DESTINS (IDEST) , DAYS (IDAY) 
TYPE 1090 
ACCEPT 1010, SEATS (ISEAT, ISMOKE+1,IDEST,IDAY) 
TYPE 1100 
ACCEPT 1010, PAYMENT 
IF ( PAYMENT(1:2) .EQ. ‘'CA') THEN 
HOWPAID(KSEAT) = 0 
ELSE IF (PAYMENT(1:2) .NE. 'CR') THEN 


GO TO 220 

ELSE 
TYPE 1110 
ACCEPT 1120, HOWPAID (KSEAT) 
IF (HOWPAID(KSEAT) .NE. 0) GO TO 260 
TYPE 1130 
GO TO 240 

END IF 

CONTINUE 

GO TO 120 

CONTINUE 

END 
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PROGRAM EXAMPLES 


PROGRAM CANCEL 

INCLUDE 'DATADESC.FOR! 

CHARACTER DESTIN*6,DAY*3,NAME* 20 ,BLANKS* 20 
DATA BLANKS/' '/ 


FORMAT(' Enter destination: ',$) 

FORMAT (A) 

FORMAT(' There are no flights to ',A) 

FORMAT(' On what day? ',$) 

FORMAT(' ',A' does not hold a seat to ',A," on ',A,' flight") 
FORMAT(" Seat number ',14,' cancelled on the ',A, 

flight next ',A) 

FORMAT(' Enter passenger name: ',S) 


TYPE 1090 

ACCEPT 1010, NAME 

TYPE 1000 

ACCEPT 1010, DESTIN 

DO 20 IDEST = 1,NDESTS 

IF (DESTIN(1:2) .EQ,. DESTINS(IDEST) (1:2)) THEN 
Go TO 40 

END IF 

CONTINUE 


TYPE 1020, DESTIN 
Go TO 10 


TYPE 1030 

ACCEPT 1010, DAY 

DO 60 IDAY = 1,NDAYS 

IF (DAY(1:2) .EQ. DAYS(IDAY) (1:2)) THEN 
Go TO 80 

END IF 

CONTINUE 

GO TO 40 


ISMOKE = 0 

DO 100 ISEAT = 1,NSEATS 

IF (SEATS (ISEAT,ISMOKE+1,IDFST,IDAY) (1:10) .EQ. NAME(1:10)) THEN 
CALL LOCKFLIGHT (IDEST, IDAY) 


GO TO 200 
END IF 
CONTINUE 
IF (ISMOKE .EQ. 0) THEN 
ISMOKE = 1 
GO TO 90 
ELSE 
TYPE 1040, NAME, DESTIN, DAY 
GO TO 900 
END IF 
JSEAT = ISEAT + (NSEATS*ISMOKR) 
KSEAT = JSEAT + (IDEST-1)*2*NSEATS + (IDAY-1) *NDESTS 


TYPE 1050, JSEAT,DESTINS (IDEST) , DAYS (IDAY) 

SEATS (ISEAT, ISMOKE+1,IDEST,IDAY) (1:20) = BLANKS(1:20) 
HOWPAID(KSEAT) = 0 

CALL UNLOCKFLIGHT 

CONTINUE 

END 


s 
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PROGRAM EXAMPLES 


PROGRAM MONITOR 
INCLUDE 'DATADESC.FOR' 


CHARACTER DESTIN*6,DAY*3,HOMERASE* 4, BLANKS*64 ,SMOKE*] 
CHARACTER TIMEDELAY*13,TOPOFSCREEN*4 


INTEGER SYSSBINTIM,SYSSSETIMR,SYSSWAI TER, SYSSCLREF ,DELAY (2) 
BYTE CTLERASE (4) ,CTLTOS (4) 
EQUIVALENCE (HOMERASE,CTLFERASE(1)), (TOPOFSCREEN,CTLTOS (1)) 


DATA CTLERASE/'18'X,'H','1B'X,'J'/,BLANKS/' “L 
DATA TIMEDELAY/'O 00:00:10.00'/ 
DATA CTLTOS/'1B'X,*Y','22'X,'20'X,'1B'X,'JS'/ 


FORMAT(' Enter flight destination: ',$) 

FORMAT (A) 

FORMAT(' There are no flights to ',A) 

FORMAT("' On what day? ',$) 

FORMAT(' ',A,'DESTIN DAY SEAT PASSENGER NAME CREDIT 


1 CARD NO. (0 IF CASH)',/,! ------ --- ---- -------------- 


1 
1050 
1060 


10 


20 


40 


60 


80 


90 


FORMAT('+',A,' ',A,' ',A,12,' ',A,110,/) 
FORMAT(' ',A) 


TYPE 1000 

ACCEPT 1010, DESTIN 

DO 20 IDEST = 1,NDESTS 

IF (DESTIN(1:2) .EQ. DESTINS(IDEST) (1:2)) THEN 
GO TO 40 

END IF 

CONTINUE 


IF (DESTIN(1:3) .EQ. 'ALL') THEN 
IDEST = -1 
GO TO 40 

END IF 

TYPE 1020, DESTIN 

GO TO 10 


TYPE 1030 

ACCEPT 1010, DAY 

DO 60 IDAY = 1,NDAYS 

IF (DAY(1:2) .EQ. DAYS(IDAY) (1:2)) THEN 


GO TO 80 
END IF 
CONTINUE 
IF (DAY(1:3) .EQ. 'ALL') THEN 
IDAY = -1 
GO TO 80 
END IF 
GO TO 40 
CONTINUE 
IF (IDEST .EQ. -1) THEN 
JDEST = 1 
KDEST = NDESTS 
ELSE 
JDEST = IDEST 
KDEST = IDEST 
END IF 
IF (IDAY .E£Q. -1) THEN 
JDAY = 1 
KDAY = NDAYS 
ELSE 
JDAY = IDAY 
KDAY = IDAY 
END IF 
TYPE 1040, HOMERASE 
LINES = 0 
DO 500 IDEST = JDEST,KDEST 
ILOOP = 0 
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DO 400 IDAY = JDAY,KDAY 
JLOOP = 0 


DO 300 ISEAT = 1,2*NSEATS 
ILOOP = ILOOP + 1 

JLOOP = JLOOP + 1 

IF (ISEAT .LE. NSEATS) THEN 


SMOKE = 'N! 

ISMOKE = 1 

JSEAT = ISEAT 
ELSE 

SMOKE = ‘S' 

ISMOKE = 2 

JSEAT = ISEAT - NSEATS 
END IF 


LSEAT = ISEAT + (IDEST-1)*2*NSEATS + (IDAY-1)*NDESTS 


IF (LINES) 100,100,99 


99 IF (ILOOP ~ 2) 100,120,140 
100 DESTIN = DESTINS (IDEST) 
GO TO 140 
120 DESTIN = BLANKS 
140 CONTINUE 


IF (LINES) 160,160,150 


150 IF (JLOOP - 2) 160, 180, 200 
160 DAY = DAYS (IDAY) 
GO TO 200 
180 DAY = BLANKS 
200 CONTINUE 
IF (SEATS (JSEAT,ISMOKE,IDEST,IDAY) (1:4) .EQ. ' ‘) THEN 
IF (ISEAT .NE. 1) THEN 
GO TO 300 
END IF 
END IF 


TYPE 1050, DESTIN,DAY,SMOKE, ISEAT,SEATS (JSEAT, ISMOKE, IDFST,IDAY) , 
1 HOWPAID (LSEAT) 
LINES = LINES + 1 
IF (LINES .GE. 19) THEN 
IX = SYSSBINTIM(%$DESCR(TIMEDELAY) , DELAY) 
IF (.NOT. IX) GO TO 900 


IX = SYSSCLREF(%VAL (1) ) 
IF (.NOT. IX) GO TO 900 
IX = SYSSSETIMR(%VAL(1),DELAY,,) 
IF (.NOT. IX) GO TO 900 
IX = SYSSWAITFR($%VAL(1)) 


IF (.NOT. IX) GO TO 900 
TYPE 1060, TOPOFSCREEN 
LINES = 0 
END IF 
300 CONTINUE 
400 CONTINUE 
500 CONTINUE 


IX = SYSSBINTIM(%DESCR(TIMEDELAY) , DELAY) 
IF (.NOT. IX) GO TO 900 

IX = SYSSCLREF(%VAL (1) ) 

IF (.NOT. IX) GO TO 900 

IX = SYSSSETIMR(%VAL (1) ,DELAY,,) 

IF (.NOT. IX) GO TO 900 

IX = SYSSWAITFR(%VAL (1) ) 


IF (.NOT. IX) GO TO 900 
TYPE 1060, TOPOFSCREEN 


GO TO 90 
900 CALL LIBSSIGNAL (%VAL (IX) ) 
END 


A DEMO .OF SHAREABLE 


FORTRAN/LIST/MACHINE CODE 
FORTRAN/LIST/MACHINE CODE 
FORTRAN/LIST/MACHINE CODE 
FORTRAN/LIST/MACHINE CODE 
FORTRAN/LIST/MACHINE CODE 
FORTRAN/LIST/MACHINE CODE 
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PURGE *.* 


UNIVERSAL=LOCK FLIGHT, UNLOCKFLIGHT 


GSMATCH=LEQUAL ,0 ,0000 


Ore ee eee 


ATABASE/SHARE=NOCOPY 
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BLDVMSAIR.COM 


COMMAND FILE TO REBUILD FROM SOURCE 
THE AIRLINE RESERVATION SYSTEM WHICH IS 


IMAGES 


DATABASE 
INTERLOCK 
RESERVE 
DISPLAY 
CANCEL 
MONITOR 


LINK/SHAREABLE/MAP/FULL/CROSS DATABASE, INTERLOCK , DATABASE/OPTIONS 
LINK/MAP/FULL/CROSS RESERVE,GETSHRIMG/OPTIONS 

LINK/MAP/FULL/CROSS DISPLAY ,GETSHRIMG/OPTIONS 

LINK/MAP/FULL/CROSS MONITOR,GETSHRIMG/OPTIONS 

LINK/MAP/FULL/CROSS CANCEL,GETSHRIMG/OPTIONS 


DATABASE.OPT 


LINK TIME OPTIONS DESCRIPTION FILE TO BUILD 
THE SHARABLE IMAGE CONTAINING THE DATA BASE AND 
THE INTERLOCK ROUTINE 


! MAKE ROUTINE ENTRY POINTS 
! ACCESSIBLE TO USER PROGRAMS 
! SET GLOBAL SECTION MATCH CONTROL 


GETSHRIMG.OPT 


LINK TIME OPTIONS FILE TO ACQUIRE THE SHARED 
DATABASE AND INTERLOCKING ROUTINE, 


! MAPPED INTO ADDRESS SPACE 


APPENDIX A 


LOCKING A RESOURCE 


A semaphore is a metering device that provides the capability of 
controlling access to a set of resources. A semaphore that controls 
access to a single resource is called a mutex (mutual exclusion) or, 
more commonly, a lock. 


You can perform two operations on a mutual exclusion semaphore (lock): 


e Lock - Test to see if the resource is free. If it is, then 
take (use) it and proceed with execution. If the resource is 
not free, execution is stalled until the resource becomes 
available. 


e Unlock - Give the resource back (make it available to others) 
when it is no longer needed. If any other processes are 
Stalled waiting for the resource, they are awakened, 


Locking and unlocking must be interlocked operations, so that no race 
conditions result. An example of a race condition is as follows: in 
the middle of the first process's test for a resource's availability, 
the resource is returned by another process, but the return goes 
unnoticed by the first process. 


Two methods of creating a lock are (1) using a common event flag or 
(2) using a queue. In selecting either method, you must consider how 
you want to service requests for the resource, how important is ease 
of use, and how quickly the method must execute. Table A-1l contrasts 
the two methods. 


Table A-1 
Two Methods of Creating a Lock 






























Event Flag Queue 

Requests serviced according 1. Requests serviced on a 

to process priority first-in first-out (FIFO) 
or a last-in first-out 
(LIFO) basis 

Easy to use 2. More complicated to use 
(requires a global sec- 
tion and special data 
structures) 

Uses time manipulating 3. Executes at hardware 

the event flag instruction speed when no 


conflict occurs 








LOCKING A RESOURCE 


A.1 USING AN EVENT FLAG 


Cooperating processes can control access to a resource by using a 
common event flag as a lock. The procedure is as follows: 


1. An initialization process is run to create a permanent common 
event flag cluster and to set the initial state of all 32 
flags to 1. This provides 32 individual locks. 


2. Each cooperating process must associate with the common event 
flag cluster. 


3. Before any process uses the resource represented by a 
particular event flag, it must execute the logic shown in 
Figure A-l. 







O¢: $CLREF_S EFN=#65 


Clear event flag 


Was previous 
state of flag = 1 


Wait for event 
flag 





Yes CMPL RO+#SS¢. WASSET 


BEQL 10% 


$WATTFR.S EFN=#G5 
BR bl 36 





Proceed to 
access 
resource 


Set event flag 


10%: ‘ ‘Proceed 


$SETEF.$ EFN=#@5 


Figure A-l Event Flaq Lock Logic 


Because the initial state of the event flag is 1, only one process at 
a time will be able to clear the event flag and find its previous 
state to be a1. All subsequent processes will find the previous 
state to be 0, and thus will wait until the owner process sets the 
flag. (This occurs when the owner process is finished with the 
resource and returns it.) 


LOCKING A RESOURCE 


Setting the event flag causes all the waiting processes to awaken and 
compete for CPU time according to their process priority (unless an 
outstanding I/0 request or some other factor prevents a 
higher-priority process from becoming computable). However, only one 
waiting process will be able to clear the event flag and find its 
previous state to be a l. (Note: Clearing an event flag is an 
interlocked operation implemented by VAX/VMS.) 


Figure A-2 is a VAX-11 FORTRAN example using a common event flag as a 
lock. Note that in Figure A-2 it is not necessary to run an 
initialization process (step 1 at the beginning of this section), 
because the program logic prevents a race condition from occurring 
during lock initialization. 


INTEGER*4 SYS$ASCEFC ,SYSS$SETEF ,SYSS$CLREF ,SYSSWAITER,STATUS 
EXTERNAL SS$_WASSET,SS$_WASCLR 


C-- Associate with a common event flag cluster to be used as a mutual exclusion 
C-- semaphore. If the cluster does not exist, it is created. The first two 
C-- flags are used to avoid any race conditions during initialization. 


STATUS = SYSSASCEFC (%VAL (64) ,"MUTEX',,) 
IF (.NOT. STATUS) CALL LIBSSTOP(%VAL (STATUS) ) 
IF (SYSSSETEF (%$VAL(64)) .EQ. $LOC(SS$_WASCLR)) THEN ! If creator 


CALL SYSSSETEF (&VAL (66) ) ! Init mutex 

CALL SYSSSETEF (%VAL (65) ) ! Set initialized 
ELSE 

CALL SYSSWAITFR (%VAL (65) ) ! Initialized wait 
END IF 


C-- Perform any other program initialization 
CONTINUE 
C-- Obtain exclusive access to the mutex to make sure no other process 
C-- will execute its critical section while we do. If the mutex cannot be 
C-- obtained, wait for it to be released. 
50 STATUS = SYSSCLREF (%VAL (66) ) 
IF (STATUS .EQ. %LOC(SS$ WASSET)) GOTO 100 


STATUS = SYSSWAITFR(%VAL(66) ) 
GOTO 50 


C-- Execute the critical section of the program 
100 CONTINUE 
C-- Release the mutex and unblock any other processes that might have 
C-- been waiting. If more than one is waiting, the first one to obtain the 
C-- the mutex will get it, and the others will fail and wait again. 
CALL SYSSSETEF (%VAL (66) ) 
GOTO 50 


END 


Figure A-~2 Event Flag Lock Example 


LOCKING A RESOURCE 


A.1.1 Shared Memory Considerations 


You can use an event flag in a shared memory common event flag cluster 
to guarantee that only one process uSeS a resource at a time, 
However, because of potential differences in the speeds and workloads 
of the processors connected to the shared memory, there is no 
assurance that the highest-priority waiting process will get the 
resource each time it becomes available, 


A.2 USING A QUEUE 


Cooperating processes can use a queue to lock a resource and, after 
unlocking, make the resource available on either a first-in first-out 
(FIFO) or last-in first-out (LIFO) basis. (Queues and the queue 
instructions are explained in the VAX-1l Architecture Handbook.) The 
procedure is as follows. 





1. An initialization process must be run to create a permanent 
global section and initialize a queue header, 


2. To use the resource represented by the queue header, each 
process must map the global section. Each process must also 
create a 3-longword description with the following format in 
the global section: 


Forward link 


Backward link 





Process ID 





3. Before any process uses the resource represented by the queue 
header, it must execute the logic shown in Figure A~3. 
(Figure A-3 shows a FIFO queuing policy. Figure A-4 later in 
this appendix shows a LIFO policy.) 
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Insert its description 


into queue at tail INSQUE DESC +@HEADER+4 
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Figure A-3 FIFO Queuing Policy 


Because the initial state of the queue is empty, only one process will 
be able to insert its entry in the queue and find it to be the first 
entry. Each subsequent process will find more than one entry after 
inserting itself, and thus will hibernate. 


LOCKING A RESOURCE 


When the owner process is finished using the resource, it simply 
removes its description from the head of the queue. If the queue is 
then empty, no process is waiting. If the queue is not empty, the 
process whose ID is first in the queue is awakened, and that process 
can now use the resource. (Note: The queue instructions are 
interlocked operations implemented by the VAX-11 processor.) 


Figure A-3 and its explanation described a FIFO queuing policy. 
Figure A-4 shows the logic for a LIFO queuing policy. 


A.2.1 Shared Memory Considerations 


The logic and coding in Section A.2 cannot be used with a queue in 
shared memory for the following reasons: 


e The Wake (SWAKE) system service cannot be used to wake a 
process running on another processor. 


e The interlocked queue instructions must be used (INSQHI, 
INSOTI, REMQHI, REMOQTI). 


To use a queue in shared memory, you must devise a more complicated 
mechanism. (Such a mechanism is beyond the scope of this manual.) 
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A-4 LIFO Queuing Policy 
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LPA11-K CONSIDERATIONS 


Users should consider three factors in selecting and using the 
Laboratory Peripheral Accelerator (LPA11-K) for a real-time 
application: 


e The effect on performance of resource availability and 
hardware configuration 


@ Throughout and response-time requirements of the application 


e The LPA11-K driver's use of parameters in data acquisition 
calls 


The remainder of this appendix discusses each of these considerations. 


B.1 RESOURCES, CONFIGURATION, AND PERFORMANCE 


One factor that determines the performance of the LPA11-K is its 
interaction with other devices and applications in the system. The 
LPA11-K is designed as a real-time device. Its function is to sample 
data synchronously with a real-time clock. However, if for any reason 
the LPA11-K cannot maintain this synchronous transfer of data, a 
nonretriable error is generated. This method of operation contrasts 
with that of a disk, which can perform a retry because the original 
data is still available (in memory for a write or on disk for a read). 
In a real-time application, however, after the event of interest has 
passed it may no longer be of interest. 


Therefore, the resources needed to carry out an application in real 
time must be guaranteed to be available. Some of the resources that 
must be available to use the LPA11-K in real time are UNIBUS' adaptor 
map registers to map the buffers, UNIBUS adaptor data path, UNIBUS 
direct memory access (DMA) transfer bandwidth, processor interrupt 
response time, memory in the working set for data buffers, and CPU 
execution time for the application program. If the application 
buffers the data for storage on disk, the following resources must 
also be available: the disk controller and drive, and sufficient 
bandwidth and adaptors for the MASSBUS or UNIBUS (depending on where 
the disk is interfaced). 


The VAX/VMS system gives the application program control over many 
system resources, to guarantee their availability when these resources 
are needed. Processes can lock critical pages, thus ensuring the 
availability of that memory. Processes can adjust their priority to 
guarantee access to CPU execution time and to mass storage 
controllers. 
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In other areas, however, control over resources is difficult, often 
because the resources are being used concurrently and involve 
interrupt handling and contention for bandwidth on I/0 _ buses, In 
fact, several studies have concluded that the major impact on LPA11-K 
performance is UNIBUS I/0 bandwidth contention. 


The LPA11-K detects two classes of errors associated with real~time 
performance: 


e Buffer overrun/underrun -- deals with the ability of the 
application program to supply new memory buffers fast enough 
(for example, to process data at least as fast as it is coming 
in) 


e Data overrun/underrun -- deals with the ability of the device 
to arbitrate for UNIBUS cycles and to transfer data to and 
from main memory 


Buffer overrun/underrun errors often reflect inadequate application 
control over resources; data overrun/underrun errors are usually 
caused by I/0 contention. . 


The first class of errors, buffer overrun/underrun, is a function of 
the application. The application must run at a priority high enough 
to guarantee it sufficient CPU time. It must also have a working set 
large enough to hold in physical memory the data buffers and the code 
that performs computation on the data, to prevent excessive paging (or 
perhaps to prevent any paging at all}. However, if these control 
measures have been taken and the buffers are large enough, and if 
buffer overrun/underrun errors still occur repeatedly, then the data 
rate is too fast for the work that needs to be done. In this case, 
the solution might be to buffer the data to intermediate mass storage 
for future processing. 


The second class of errors, data overrun/underrun, is a function of 
UNIBUS and memory I/O contention. As other DMA devices on the UNIBUS 
become concurrently active, the effective throughput rate of the 
LPA11-K can be significantly reduced. If LPA11-K throughput falls 
below the application's requirements, an additional UNIBUS adaptor may 
be needed. 


B.2 THROUGHPUT AND RESPONSE-TIME REQUIREMENTS 


The LPA11-K and its support under VAX/VMS are tailored primarily for 
throughput-intensive applications. This device can recognize a simple 
event, such as a single digital signal, and start data acquisition 
when the event occurs. However, if the application must respond 
quickly to events represented by the contents of the data being 
acquired, the LPA11-K might not be suitable for two reasons: 


e The LPA11-K samples analog or digital data and stores it in 
large data buffers in main memory, generating an interrupt 
only when a buffer is full. Thus, if the application must 
detect a particular data value and respond quickly, it might 
have to wait for an entire buffer to be filled before it could 
start searching for the value. 


e VAX/VMS is designed to manage LPA11-K data buffers 
transparently for application programs. This buffer 
Management involves some software overhead. Thus, if data 
buffers were made very small (the smallest being one data 
point per buffer) in an effort to access data points sooner, 
the software overhead would grow considerably. 
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B.3 PARAMETERS FOR DATA ACQUISITION CALLS 


The LPA11-K uses parameters in some data acquisition procedures. For 
example, assume that an application must acquire a stream of analog 
data from several points at a specific rate per point, store the 
digitized data in memory, and stop when enough data has been taken. 


To accomplish these goals, you must Specify the following parameters: 
analog-to-digital conversion, the analog data channels to sample, the 
Sample rate, the place in memory to store the data, and the amount of 
data to be taken. At the start of each data acquisition session, the 
application provides these values aS parameters to the LPA11-K driver. 


Data acquisition calis using parameters have the advantages of 
isolating the application from the actual hardware and simplifying the 
programming: the application programmer does not need to write 
interrupt service routines in assembly language or microcode. 
However, this approach might not be adequate for certain complicated 
applications requiring a sophisticated sampling algorithm or complex 
interactions between multiple data acquisition streams. If the 
application requires capabilities not provided by the LPA11-K 
parameters, other devices should be investigated. 
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VAX-11 BLISS-32 PROGRAM EXAMPLE 


This appendix shows a VAX-11 BLISS-—32 program using 

connect-to-interrupt capability. The functions performed by 
program are described in the “Abstract" near the beginning of 
listing and in comments throughout the program. This program is 
a simple illustration of connecting to an interrupt vector and 

not reflect a typical real-time situation (for example, the 
printer is not a real-time device). 


MODULE lpmultast (8TITLE'line printer driver' MAIN=lp main, IDENT='X02')= 


COPYRIGHT (c) 1980 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 


! 
1 
! 
! 
! 
! 
! 
i] 
! 
! 
i] 
! 
t 
t 
! 
! DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
! SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 

{ 

t++ 

! 

t 

, 

! 

t 

! 

! 

! 

1 

i 

! 

! 


FACILITY: 


A sample program that illustrates the use of the connect to 
interrupt facility. 


ABSTRACT: 


This program assigns a channel to a line printer device, and 
then connects to the device via the connect to interrupt 
facility. The program then requests the name of a file from 
the user, and outputs that file on the line printer. 

! 

[-- 

SSBTTL ‘External and local symbol definitions’ 

BEGIN 


LIBRARY 'SYSSLIBRARY:LIB'; ! Get important definitions 


PSECT 


the 
the 
the 
only 
does 
line 


VAX-11 BLISS-32 PROGRAM EXAMPLE 


+ 
Define some PSECTs which we will need to refer to later 


OWN= sharedata (ALIGN(9),WRITE), 
OWN= data; 
LINKAGE 
intrupt= JSB(REGISTER=2, REGISTER=4, REGISTER=5): 
NOPRESERVE(0,1,2,3,4) NOTUSED(6,7,8,9,10,11), 
cancel= JSB(REGISTER=2, REGISTER=3, REGISTER=4, REGISTER=5): 


NOTUSED (6,7,8,9,10,11); 


FORWARD ROUTINE 


lp_interrupt: intrupt PSECT(sharedata), ! Interrupt server 
lp cancel: NOVALUE cancel PSECT(sharedata), ! Cancel I/0 
lp_main, 


lp_isr_ast, 
lp_iodone_ast; 


! Static Definitions 


LITERAL 
true = oy 
false = 0, 
io_page_count =l, ! Pages needed in UNIBUS I/O space 
jo_space_base = %x'20100000', ! Physical address of UBA 0 space 
! for VAX-11/780. Other processors 
! need different magic number... 
unibus_ lp _addr= %0'777514', ! 18-bit addr of LP11l CSR 


OWN 


i] 
! Calculate the page-frame number to map to get the physical address 
! that the unibus is mapped on. 

! 

io_page_pfn = (io_space_base + unibus lp_addr)/51l2, 

Ip_csr_offset = %0'514', ! Offset to printer CSRs. 


filename length = 100, 


record bufsiz = 256, 

prompt length = 28; 

ipchan: WORD, { Line printer channel number. 
filename_buffer: VECTOR[filename_length,BYTE], 

file descr: VECTOR[2] INITIAL( filename_length, filename_buffer), 
fdlen: WORD, 

record buffer: VECTOR[record bufsiz,BYTE], 

file fab: Sfab ( ! Input file fab 
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Functional description: 


This routine services an interrupt from the line printer 

device. If the interrupt was expected, the routine disables 
output interrupts. The disable is an optimization to prevent one 
interrupt per character. With output interrupts disabled, the 
line printer buffers characters until the device needs to output 
the characters. Then the main program enables output interrupts 
only for the period of time necessary for the device to empty 
the buffer. 


Then the interrupt service routine loads a success status into 
RO and returns. 


If the interrupt was not expected, the routine just loads 
an error status into RO to prevent delivery of an AST to the 
owning process and returns. 


Inputs: 
R2 - address of a counted argument list 
R4 - address of the IDB 
R5 - address of the UCB 


The counted argument list is as follows: 


nr en nn a a a | 


O(R2) - count of arguments (4) 
4(R2) - the system-mapped address of the user buffer 
8(R2) - the system-mapped address of the device's CSR 
12(R2) ~ the IDB address 
16(R2) - the UCB address 
Outputs: 
The routine must preserve all registers except RO-R4. 
BEGIN 
MAP 
arglist: REF VECTOR[,LONG], 
ucb: REF BLOCK[,BYTE], 
idb: REF BLOCK[,BYTE]; 
BIND 
bufadr = arglist[1l]: REF BLOCK FIELD (buf); ! System adr of buffer 
BUILTIN 
TESTBITCC; 
IF TESTBITCC( bufadr[buf$l_ flags] ) 
THEN 
RETURN 0; ! No interrupt expected, no AST wanted 
(.idb[idb$1_csr])<0,16> = 0; ! Disable the output interrupt 


ss$_normal 
END; 
tSBTTL ‘LP CANCEL, Cancel I/O on Line Printer' 


ROUTINE lp_cancel( chan_idx, irp, pcb, ucb ): NOVALUE cancel PSECT(sharedata)= 
I++ 


{ Functional description: 
! 
! This routine disables output interrupts from the line printer. 
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fac=get, 
fna=filename_buffer, 
org=seq, 

rfim=var, 
dnm='TEST.LIS'), 


file rab: Srab ( 
fab=file fab, 
rac=seq,_ 
ubf=record buffer, 
usz=record bufsiz), 


io_page_limits: VECTOR [2] ! Addresses of process-mapped 
INITIAL (200, ! UNIBUS I/O page. 200 tells SCRMPSC 
200); 1 to map pages in PO space 
BIND 
onesecond delta= ! Delta time format for one 
UPLIT (~10*1000*1000,~1); ! second. 
+ 


Define offsets into the buffer that will be shared by the user 
process and the process routines that execute in kernel mode. 


FIELD 
buf= 
SET 
buf$1_flags= {0,0,32,0], ! Flags longword. 
buf$v_int= [0,0,1,0], t Interrupt expected 
buf$w_charcount=[4,0,16,0], ! Number of chars in buffer 
buf$1_startdata=[8,0,32,0] | Start of data in buffer. 
TES, 
lp= 
SET 
lp_csr= {0,0,16,1], ! Offset to line printer CSR 
lp_dbr= [2,0,8,0] ! Offset to line printer data 
TES; 
$SBTTL 'Double Mapped Page Buffers' 
OWN 
output_buffer: BLOCK (512,BYTE] FIELD(buf) PSECT(sharedata); 
PSECT 
OWN= sharedata, 
PLIT= sharedata; 


I 
! The routines to be executed in kernel mode must follow directly 
! after this allocation of bytes to hold output data. 

' 

‘SBTTL ‘LP_INTERRUPT, Interrupt service routine' 


ROUTINE lp_interrupt( arglist, idb, ucb ): intrupt PSECT(sharedata)= 
Y+4+ 
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! 
! Inputs: 
! 
1 R2 - negated value of the channel index number 
! R3 - address of the current IRP (I/O request packet) 
! R4 - address of the PCB (process control block) for the 
! process canceling I/0 
! R5 - address of the UCB (unit control block) 
! 
! Outputs: 
! 
t none 
1 
t-- 
BEGIN 
MAP 
irp: REF BLOCK[,BYTE], 
peb: REF BLOCK[,BYTE], 
ucb: REF BLOCK[,BYTE]; 
BIND 
crb= -ucb(ucb$1_crb]: BLOCK[,BYTE]; 
LOCAL 
csr: REF BLOCK[,BYTE] FIELD(1p); ! UNIBUS addr. 
esr = ..(crb[crb$l_intd]) + BLOCK[0, vec$l_idb;0,BYTE]); ! Addr of CSR 
esr{lp_csr] = 0 ! Disable output interrupts. 
END; 


$SBTTL 'LP_MAIN, the main routine' 

ROUTINE lp_main: PSECT(S$CODES) = 

t 

| LP MAIN, the routine that controls the others 
Functional description: 


1. Assign a channel to the line printer. 


i] 
i] 
' 
£ 
! 2. Map the process to the I/O page. 
! 3. Issue a connect to interrupt QIO to get the line printer. 
! 4. Prompt the user for a file name. 
! 5. Open and connect to the file. 
1 6. Write the contents of the file to the line printer. 
! 
! Inputs: 
! 
! none 
! 
! Outputs: 
! 
] RO ~ status code 
! SSS_NORMAL - success 
! RMS code - error in opening or reading 
! the file 
! SS$_DEVOFFLINE - error is writing to printer 
t 
[-- 
BEGIN 
PSECT 


VAX-11 BLISS-32 PROGRAM EXAMPLE 


OWN= SOWNS; 
OWN 
buffer desc: VECTOR[2] INITIAL( 
‘7 §12+512, 
output_buffer), 


Descriptor of buffer shared 
by process and kernel mode 
process routines. 


entry list: VECTOR[4] INITIAL ( 
0, 
0, 
lp interrupt~-output buffer, 
lp_cancel-output_ buffer); 


List of offsets to kernel 

mode routines: init device; 
Start device; 
interrupt servicing; 
cancel I/0. 


LOCAL 


csr: REF BLOCK[,BYTE] FIELD(lp) VOLATILE, 
status; 


EXTERNAL ROUTINE 
libSget_input; 


Assign a channel to the line printer. 


status = Sassign ( ! Assign channel to line 
devnam=SDESCRIPTOR('LPAO'), ! printer 
chan=Ipchan); 


IF NOT .status THEN RETURN .status; 


Map the UNIBUS I/O page to the process so that the line printer's 
device reqisters are accessible. 


status = Scrmpsc( ! Map I/O page to process. 
inadr=io page limits, 
retadr=io page limits, 
flags=secSm wrt OR sec$m pfnmap OR secS$m expreg, 
pagent=io page count, y ie 
vbn=io_page_pfn ); 


IF NOT .status THEN RETURN .status; 


Issue a connect to interrupt QIO to the line printer device. This 
connection will allow the program to control and handle interrupts 
from the device. 


status = $qio( ! Connect the process to the 
chan=.lpchan, ! line printer device. 
func=ioS conintread, ! Specify a read only buffer. 
astadr=lp_iodone_ast, ! Specify an AST routine. 
pl=buffer desc, ! Specify a shared buffer. 
p2=entry list, ! Specify routine entry points. 
p3=cin$m isr OR cinS$m cancel, 
= ~ ! Specify ISR, cancel routines. 
p4=lp_isr_ast, ! Specify an interrupt AST. 
p6=5)7 ! Specify an AST count. 


IF NOT .status THEN RETURN .status; 


‘= 
| 
n 
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! Ask user what file to print, 


status = lib$get_input( file descr, 


Sdescriptor('Name of file to be printed: '), 
file descr [0}); 


IF NOT .status THEN RETURN .status; 


Open and connect file. 


file fab[fab$b_fns] = «file descr [0]; ! Length of spec. 
status = Sopen(fab=file fab); ! Open file. 
IF NOT .status THEN RETURN .status; 


status = $connect( rab = file rab ); ! Connect file. 


IF NOT .status THEN RETURN .status; 


Get a record at a time until end of file. Surround record's contents 
with a linefeed and a carriage return. 


WHILE status = $get(rab=file rab) DO 


BEGIN 
LOCAL 
inp, 
outp; 
outp = output buffer [buf$l startdata]; ! Target for first character 
CHSWCHAR_A( %CHAR(%X'A'), outp); ! Start with a line-feed 


inp = record buffer; 


! 
! Load length of this output buffer in the buffer header. Then copy 

! the contents of the input buffer to the output buffer. Translate all 
! lower case alphabetics to upper case characters. 

! 


output_buffer[{buf$w_charcount] = .file rab[rabSw_rsz] + 2; 


DECR i FROM .file_rab[rab$w_rsz]-l1 TO 0 DO 
BEGIN ~ 
LOCAL 
char; 


char = CHS$RCHAR A( inp ); 

SELECTONE .char OF 
SET 
(sC'a' TO $C'z']: char = .char - %X'20'; ! Upcase 
TES; 


CHSWCHAR_A( .char, outp ) 


ee 
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END; 


CHSWCHAR_A( $CHAR(%X'OD'), outp ); ! Put CR at end. 


Send characters one at a time to the line printer. Before sending a 
character, see if the line printer is still in ready state. If not, 
set a timer to go off in one second, and go to sleep. When an AST 
occurs -- either because of a line printer interrupt, or because 
the timer runs out, the AST routine will wake the process up again. 


If the line printer is still in ready state, just send the next 
character. 


outp = output_buffer[buf$l_ startdata]; ! Addr of output string 
csr = .io_ page limits + lp_csr_offset; ! Addr of LP's CSR 


DECR i FROM .output_buffer[buf$w_charcount]-1 TO 0 DO 
WHILE 1 DO 
BEGIN 
BIND 


devbits= csr{lp_csr]: VOLATILE SIGNED WORD; 


CASE SIGN(.devbits) FROM -1 TO 1 OF 


SET 
[-l]: RETURN ss$_devoffline; ! Paper problem, maybe 
fl]: BEGIN ! Output a character 
esr(1lp_dbr] = CHSRCHAR_A( outp ); 
EXITLOOP ! Back for next char 
END; 
{O]: + 


i 

! Line printer is not ready. See whether it's in 
! trouble, or just busy. If it's in trouble, stop 
! program with error status. Otherwise, just wait 
! until it comes ready again. 


BEGIN 

output _buffer{bufSv_int] = true; ! Interrupt expected 
esr{lp csr] = .csr{Ip csr] OR %X'40'; ! Enable LP interrupts 
status = $setimr ( = ! Set a one second timer. 


daytim=onesecond delta, 
astadr=lp_isr_ast); 


IF NOT .status THEN RETURN .status; 


Shiber; ! Go to sleep. 
Scantim() ! Cancel timer request 
END 
TES 
END 
END; ! End $GET loop 


IF .status NEQ ss$_endoffile 
THEN 
RETURN .status; 


APPENDIX D 


REAL-TIME OPTIMIZATION CHECKLIST 


This appendix lists suggestions that usually improve real-time program 
performance. There is no guarantee, however, that any suggestion is 
appropriate for all applications. You must consider the needs of each 
application and the overall system activity when you evaluate any 
suggestion. 


1. 


Avoid costly operations in time-critical code, Costly 
operations include: 


a. File opens or extensions 

b. Mailbox creation 

c. Common event flag cluster creation 

d. Device allocation 

e. Error reporting 

Avoid window turns on critical files. Suggestions: 
a. Use contiguous files 

b. Specify a large window size 


Inhibit system paging. Specify parameter values to the 
SYSGEN utility to: 


a. Disable system code paging (SYSPAGING = 0) 

b. Disable paging of pageable dynamic pool (POOL PAGING = 0) 
c. Specify a large system working set (SYSMWCNT) 

However, before adjusting any of the parameter values, read 


the explanation of the parameter and any cautions in the 
VAX/VMS System Manager's Guide. 





Use the Queue I/O Request (SQIO) system service directly for 
Ifo. 


a. Setting an event flag is the fastest means of signalling 
I/O completion 


b. Using an AST is more time-consuming 
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Global sections provide’ the 
interprocess communication. 


Waiting for an event flag and 


lowest-overhead means of 


uSing hibernate/wake 


the fastest methods of interprocess signalling. 


provide 


INDEX 


A 


Accessing device registers, 4-10 

ACP (ancillary control process), 
4-2 

Adjust Working Set Limit 
(SADJWSL) system service, 2-6 

Airline reservation system 
(example), 7-45 to 7-53 

Allocation, device, 1-4 

Ancillary control process (ACP), 
4-2 

Associate Common Event Flag Clus- 
ter (SASCEFC) system service, 


3-3 
Asynchronous system trap (AST), 
3-8 
conditions preventing delivery, 
3-9 
effect of access mode on deli- 
very, 3-8, 3-9 


service routine, 


3-8, 3-9 


Balance set, 2-5 

lock working set in, 2-8 
Base priority (process), 1-9, 1-11 
BLISS-32 example, C-1 to C-8 


C 


Change-mode vector, 6-2, 6-3 
Common event flags, 3-2 to 3-4 
associating with a cluster, 3-3 
creating a cluster, 3-3 
mutex use, A-2 to A-4 
shared memory, 5-5, 5-4 
permanent clusters, 3-3 
setting, 3-3, 3-4 
temporary clusters, 3-2 
waiting for, 3-4 
Condition handling, 1-4 
CONINTERR, 4-13, 4-14 
Connect-to-interrupt capability, 


AST service routine, 4-14 to 
4-16 

benefits, 4-6, 4-7 

cancel I/O routine, 4-21, 4-22 


conventions for user routines, 
4-18 to 4-22 
device initialization routine, 


4-20 

disconnecting, 4-15, 4-18, 4-21, 
4-22 

driver, 4-13, 4-14 


Connect-to-interrupt 
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interrupt service routine, 
4-14, 4-15, 4-16, 4-18, 
4-19, 4-21 
IPL, significance of, 
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Create Process (SCREPRC) 
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connect-to-interrupt, 4-13, 
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Event flags, common (see "Common 
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accessing device register, 
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Mapping, 3-12, 
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4-11, 4-12 
Interrupt service routine (user- 
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uSing an event flag, A-2 to A-4 
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Lock Pages in Working Set (SLKWSET) 
system service, 2-6, 2-7 

Logical name translation (shared 
memory facilities), 5-3, 
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M 


MA780 (See "Shared (multiport) 
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creating, 3-5 
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permanent, 3-5 
process termination, 3-5 
shared memory, 5-6, 5-7 
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Memory, 
lock pages in, 2-7, 2-8 
lock process working set in, 

2-8 

Memory management, 
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installing, 6-5 
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purpose, 6-1 
using, 6-5 
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Process quotas (See "Quotas") 
Process swap mode, 2-8 
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Programming suggestions, 3-10, 
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access errors, 4-9 
power failure, 4-9 
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User privileges (See "Privileges") 
User-written system services (see 
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State... Zip Code 





or 
Countrv 
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